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Technical Note #0 (this document) accompanies each release of Technical Notes. This 
release includes notes number 129 (revised), 163, 164, 165, 166, 167, 168, 169, 170, 
171, 172, 173, 174, 175, 176, 177, 178, 179, 180, 181, 182, and 183 as well as an index 
to Macintosh Technical Notes. If there are any subjects which you would like to see 
treated in a Technical Note (or if you have any questions about existing Technical 
Notes), please send us a note at the following address: 


Macintosh Technical Notes 

c/o Apple Computer 

20525 Mariani Ave. MS 27-T 
Cupertino, CA 95014 

MCI: MACTECH 

AppleLink: MACDTS 


We want Technical Notes to be distributed as widely as possible, so they are sent to all 
certified developers at no charge; they are also posted on AppleLink on the Dev Tech 
Supt bulletin board. Another way to get them is to join the Apple Programmer's and 
Developer's Association and to auto-order Macintosh Technical Notes. As an APDA 
member, you'll have access to the tools and documentation you'll need to develop 
Apple-compatible products—all with one easy phone call. To get an application to 
become an APDA member, just write or call: 


Apple Programmer's and Developer’s Association 
290 SW 43rd Street 

Renton, WA 98055 

(206) 251-6548 

MCI: 312-7449 

AppleLink: APDA 


We place no restrictions on copying Technical Notes {except that they cannot be resold), 
so read, enjoy and share. 


We hope that Macintosh Technical Notes will provide you with lots of valuable 
information while you’re developing Macintosh software. 


The following pages list all Macintosh Technical Notes that have been released (both by 
number and by subject). 
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#40: Finder Flags 


See also: The File Manager 
Written by: Jim Friedlander June 16, 1986 
Modified by: Jim Friedlander March 2, 1987 





rearea a a 


This revision corrects the meanings of bits 6 and 7, which were 
interchanged in the original version of this technical note. ResEdit uses the 
bits incorrectly in versions prior to 1.1D3. 





The Finder keeps and uses a series of file information flags for each file. These flags 
are located in the faF lags field (a word at offset $28 into an HParamBlockRec) of the 
ioFlFndriInfo record of a parameter block. These flags may change with newer 
versions of the Finder. Finder 5.4 assigns the following meaning to these flags: 


Bit Meaning 

0 Set if file/folder is on the desktop (Finder 5.0 and later) 

1 bFOwnAppl (used internally) 

2 reserved, currently unused 

3 reserved, currently unused 

4 bFNever (never SwitchLaunch) (not implemented) 

5 bFAlways (always SwitchLaunch) 

6 Set if application is shared and is opened read-only (128K ROM only) 
7 Set if file should be cached (not implemented) 

8 Inited (seen by Finder) 

9 Changed (used internally by Finder) 

10 Busy (copied from File System busy bit) 

11 NoCopy (not used in 5.0 and later, formerly called BOZO) 
12 System (set if file is a system file) 

13 HasBundle 

14 Invisible 

15 Locked 
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#57: Macintosh Plus Overview 


See: Inside Macintosh volume 
IV 

Written by: Scott Knaster January 8, 1986 

Modified by: Louella Pizzuti May 4, 1987 


a 


Technical Note 57 was originally meant as interim Macintosh Plus documentation and 
it has been replaced by Inside Macintosh volume IV, which is more complete and more 
accurate than Technical Note 57. 
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#57a: Macintosh Plus Overview (update) 


See: Inside Macintosh volume 
IV 

Written by: Scott Knaster January 8, 1986 

Modified by: Louella Pizzuti May 4, 1987 


Technical Note 57a was originally meant as interim Macintosh Plus documentation and 
it has been replaced by Inside Macintosh volume IV. Please refer to Inside Macintosh 
instead of this technical note. 


Technical Note #57a page 4 of1 Macintosh Plus Overview (update) 


Macintosh Technical Notes 3 


#91: Optimizing for the LaserWriter—Picture Comments 


See also: The Print Manager 

QuickDraw 

Technical Note #72: Optimizing for the LaserWriter— 
Techniques 

Technical Note #27: MacDraw Picture Comments 

PostScript Language Reference Manual, Adobe Systems 

PostScript Language Tutorial and Cookbook, Adobe 
Systems 

LaserWriter Reference Manual 


Written by: Ginger Jernigan November 15, 1986 
Modified by: Ginger Jernigan March 2, 1987 





This technical note is a continuation of Technical Note #72: Optimizing for 
the LaserWriter. This technica! note discusses the picture comments that 
the LaserWriter driver recognizes. 


This technical note has been modified to include corrected descriptions of 
the SetLineWidth, PostScriptFile and ResourcePS comments and to 
include some additional warnings. 





The implementation of QuickDraw’s picComment facility by the LaserWriter driver 
allows you to take advantage of features (like rotated text) which are available in 
PostScript but may not be available in QuickDraw. 


Warning: Using PostScript-specific comments will make your code printer-dependent 
and may cause compatibility problems with non-PostScript devices, so don't use them 
unless you absolutely have to. 


Some of the picture comments below are designed to be issued along with QuickDraw 
commands that simulate the commented commands on the Macintosh screen. When 
the comments are used, the accompanying QuickDraw comments are ignored. If you 
are designing a picture to be printed by the LaserWriter, the structure and use of these 
comments must be precise, otherwise nothing will print. If another printer driver (like 
the ImageWriter I/II driver) has not implemented these comments, the comments are 
ignored and the accompanying QuickDraw commands are used. 
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Some of these comments are also implemented by MacDraw. Please take a look at 
Technical Note #27 for a description of their use by MacDraw. 


Below are the picture comments that the LaserWriter driver recognizes: 


Type Kind Data Size Data Description 
TextBegin 150 6 TTxtPicRec Begin text function 
TextEnd LoL 0 NIL End text function 
StringBegin 152 0 NIL Begin pieces of original string 
StringEnd 153 0 NIL End pieces of original string 
TextCenter 154 8 TTxtCenter Offset to center of rotation 
* LineLayoutoff 155 0 NIL Turns LaserWriter line layout off 
* LineLayoutOn 156 0 NIL Turns LaserWriter line layout on 
PolyBegin 160 0 NIL Begin special polygon 
PolyEnd 161 0 NIL End special polygon 
Polylgnore 163 0 NIL Ignore following poly data 
PolySmooth 164 1 PolyVerb Close, Fill, Frame 
picPlyClo 165 0 NIL Close the poly 
* DashedLine 180 - TDashedLine Draw following lines as dashed 
* DashedStop 181 0 NIL End dashed lines 
* SetLineWidth 182 4 Point Set fractional line widths 
*PostScriptBegin 190 0 NIL Set driver state to PostScript 
* PostScriptEnd 191 0 NIL Restore QuickDraw state 
*PostScriptHandle 192 - PSData PostScript data in handle 
* PostScriptFile 193 - FileName FileName in data handle 
*TextIsPostScript 194 0 NIL QuickDraw text is sent as PostScript 
* ResourcePS 195 8 Type/ID/index PostScript data in a resource file 
**RotateBegin 200 4 TRotation Begin rotated port 
**RotateEnd 201 0 NIL End rotation 
**RotateCenter 202 8 Center Offset to center of rotation 
**FormsPrinting 210 0 NIL Don’t clear print buffer after each 
page 
**EndFormsPrinting 211 0 NIL End forms printing after PrClosePage 


* These comments are only implemented in LaserWriter driver 3.0 or later. 
** These comments are only implemented in LaserWriter driver 3.1 or later. 


Each of these comments are discussed below in six groups: Text, Polygons, Lines, 
PostScript, Rotation, and Forms. Code examples are given where appropriate. For 
other examples of how to use picture comments for printing please see the Print 
example program in the Software Supplement (currently available through APDA as 
“Macintosh Example Applications and Sources 1.0”). 


Note: The examples used in the LaserWriter Reference Manual are incorrect. Please 
use the examples presented here instead. 


Text 


In order to support the What-You-See-ls-What-You-Get paradigm, the LaserWriter 


Optimizing for the LaserWriter 
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driver uses a line layout algorithm to assure that the placement of the line on the printer 
closely approximates the placement of the line on the screen. This means that the 
printer driver gets the width of the line from QuickDraw, then tells PostScript to place 
the text in exactly the same place with the same width. 


The TextBegin comment allows the application to specify the layout and the 
orientation of the text that follows it by specifying the following information: 


TTxtPicRec = packed Record 


tJus: Byte; {0,1,2,3,4 or greater => none, left, center, right, full 
justification } 

tFlip: Byte; {0,1,2 => none, horizontal, vertical coordinate flip } 

tRot: Integer; {0..360 => clockwise rotation in degrees } 

tLine: Byte; {1,2,3.. => single, 1-1/2, double.. spacing } 

tCmnt: Byte; {Reserved } 


End; { TTxtPicRec } 


Left, right or center justification, specified by tJust, tells the driver to maintain only the 
left, right or center point, without recalculating the interword spacing. Full justification 
specifies that both endpoints be maintained and interword spacing be recalculated. 
This means that the driver makes sure that the specified points are maintained on the 
printer without caring whether the overall width has changed. Full justification means 
that the overall width of the line has been maintained. tFlip and tRot specify the 
orientation of the text, allowing the application to take advantage of the rotation features 
of PostScript. tLine specifies the interline spacing. When no TextBegin comment is 
used, the defaults are full justification, no rotation and single-spaced lines. 


String Reconstruction 


The StringBegin and StringEnd comments are used to bracket short strings of text 
that are actually sections of an original long string. MacDraw, for instance, breaks jong 
strings into shorter pieces to avoid stack overflow problems with QuickDraw in the 64K 
ROM. When these smaller strings are bracketed by StringBegin and StringEnd, the 
LaserWriter driver assumes that the enclosed strings are parts of one long string and 
will perform its line layout accordingly. Any erasing or filling of background rectangles 
should take place before the StringBegin comment to avoid confusing the process of 
putting the smaller strings back together. 


Text Rotation 


In order to rotate a text object, PostScript needs to have information concerning the 
center of rotation. The TextCenter comment provides this information when a rotation 
is specified in the TextBegin comment. This comment contains the offset from the 
present pen location to the center of rotation. The offset is given as the y-component, 
then the x-component, which are declared as fixed-point numbers. This allows the 
center to be in the middle of a pixel. This comment should appear after the TextBegin 
comment and before the first following StringBegin comment. 


The associated comment data looks like this: 


TTxtCenter = Record 
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y,x: Fixed; {offset from current pen location to center of rotation) 
End; { TTxtCenter } 


Right after a Text Begin comment, the LaserWriter driver expects to see a TextCenter 
comment specifying the center of rotation for any text enclosed within the text comment 
calls. it will ignore all further CcopyBits calls, and print all standard text calls in the 
rotation specified by the information in TTxtPicRec. The center of rotation is the offset 
from the beginning position of the first string following the TextCenter comment. The 
printer driver also expects the string locations to be in the coordinate system of the 
current QuickDraw port. The printer driver rotates the entire port to draw the text so it 
can draw several strings with one rotation comment and one center comment. It is 
good practice to enclose an entire paragraph or paragraphs of text in a single rotation 
comment so that the driver makes the fewest number of rotations. 


The printer driver can draw non-textual objects within the bounds of the text rotation 
comments but it must unrotate to draw the object, then re-rotate to draw the next string 
of text. To do this the printer driver must receive another Text Center comment before 
each new rotation. So, rotated text and unrotated objects can be drawn inter-mixed 
within one TextBegin/TextEnd comment pair, but performance is slowed. 


Note that all bit maps and all clip regions are ignored during text rotation so that clip 
regions can be used to clip out the strings on printers that can’t take advantage of these 
comments. This has the unfortunate side effect of not allowing rotated text to be 
clipped. 


Rotated text comments are not associated with landscape and portrait orientation of the 
printer paper as selected by the Page Setup dialog. These are rotations with reference 
to the current QuickDraw port only. , 


All of the above text comments are terminated by a TextEnd comment. 
Turning Off Line Layout 


lf your application is using its own line layout algorithm (it uses its own character widths 
or does its own character or word placement), the printer driver doesn't need to do it 
too. To turn off line layout, you can use the LineLayoutoff comment. LineLayoutOn 
turns it on again. 


Turning on FractEnable for the 128K ROMs has the same effect as LineLayoutoff. 
When the driver detects that FractEnable has been turned on, line layout is not 
performed. The driver assumes that all text being printed is already spaced correctly 
for the LaserWriter and just sends it as is. 


Polygons 


The polygon comments are recognized by the LaserWriter driver because they are 
used by MacDraw as an alternate method of defining polygons. 


The PolyBegin and PolyEnd comments bracket polygon line segments, giving an 


Technical Note #91 page, of 16 Optimizing for the LaserWriter 


alternate way to specify a polygon. All StdLine calls between these two comments are 
part of the polygon. The endpoints of the lines are the vertices of the polygon. 


The picPlyClo comment specifies that the current polygon should be closed. This 
comes immediately after PolyBegin, if at all. It is not sufficient to simply check for 
begPt = endPt, since MacDraw allows you to create a “closed” polygon that isn't 
really closed. This comment is especially critical for smooth curves because it can 
make the difference between having a sharp corner or not in the curve. 


These comments also work with the StdPoly call. Ifa FillRgn is encountered before 
the PolyEnd comment, then the polygon is filled. Unlike QuickDraw polygons, 
comment polygons do not require an initial MoveTo call within the scope of the polygon 
comment. The polygon will be drawn using the current pen location at the time the 
polygon comment is received. The pen must be set before the polygon comment is 
called. 


Splines 


A spline is a method used to determine the smallest number of points that define a 
curve. In MacDraw, splines are used as a method for smoothing polygons. The 
vertices of the underlying unsmoothed polygon are the contro! nodes for the quadratic 
B-spline curve which is drawn. PostScript has a direct facility for cubic B-splines and 
the LaserWriter translates the quadratic B-spline nodes it gets into the appropriate 
nodes for a cubic B-spline that will exactly emulate the original quadratic B-spline. 


The PolySmooth comment specifies that the current polygon should be smoothed. 
This comment also contains data that provides a means of specifying which verbs to 
use on the smoothed polygon: | 


TPolyVerb = packed Record 
f7, £6, £5, £4, £3, £PolyClose, fPolyFill, fPolyframe : Boolean; 
End; { TPolyVerb } 


Bits 7 through 3 are not currently assigned. 


Although the closing information is redundant with the picPlyClo comment, it is 
included for the convenience of the LaserWriter. 


The LaserWriter uses the pen size at the time the PolyBegin comment is received to 
frame the smoothed polygon if framing is called for by the TPolyVerb information. 
When the PolyIgnore comment is received by the LaserWriter driver, all further 
StdLine calls are ignored until the PolyEnd comment is encountered. For polygons 
that are to be smoothed, set the initial pen width to zero after the PolyBegin comment 
so that the unsmoothed polygon will not be drawn by other printers not equipped to 
handle polygon comments. To fill the polygon, call stdRgn with the fill verb and the 
appropriate pattern set, as well as specifying fill in the PolySmooth comment. 


Lines 
The DashedLine and DashedLineStop comments are used to communicate 
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PostScript information for drawing dashed lines. 


The DashedLine comment contains the following additional data: 


TDashedLine = packed Record 
offset: SignedByte; {Offset as specified by PostScript} 
centered: SignedByte; {Whether dashed line should be 
centered to begin and end points} 
dashed: Array(0..1] of SignedByte; {lst byte is # bytes following} 
End; { TDashedLine } 


The printer driver sets up the PostScript dashed line command, as defined on page 
214 of Adobe’s PostScript Language Reference Manual, using the parameters 
specified in the comment. You can specify that the dashed line be centered between 
the begin and end points of the lines by making the centered field nonzero. 


The SetLinewidth comment allows you to set the pen width of all subsequent objects 
drawn. The additional data is a point. The vertical portion of the point is the numerator 
and the horizontal portion is the denominator of the scaling factor that the horizontal 
and vertical components of the pen are then multiplied by to obtain the new pen width. 
For example, if you have a pen size of 1,2 and in your line width comment you use 2 for 
the horizontal of the point and 7 for the vertical, the pen size will then be (7/2)"1 pixels 
wide and (7/2)*2 pixels high. 


Below is an example of how to use the line comments: 


Procedure LineTest; 
{This procedure shows how to do dashed lines and how to change the line width} 
CONST 

DashedLine = 180; 

DashedStop = 181; 

SetLineWidth = 182; 


TYPE 

DashedHdl = “DashedPtr; 

DashedPtr = “TDashedLine; 

TDashedLine = packed Record 
offset: SignedByte; 
Centered: SignedByte; 
dashed: Array[{0..1] of SignedByte; { the Oth element is the length } 

End; { TDashedLine } 

widhdl = “*widptr; 

widptr = “widpt; 

widpt = Point; 


VAR 
arect : rect; 
Width : Widhdl; 


dashedln : DashedHdl; 


Begin {LineTest} 
Dashedin := dashedhdl (NewHandle (sizeof (tdashedline) )); 
Dashedln^^.offset := 0; { No offset} 
Dashedin**.centered := 0; { don’t center} 
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Dashedlin**.dashed[0] := 1; { this is the length } 
Dashedin**.dashed[1] := 8; { this means 8 points on, 8 points off } 


Width := widhdl (NewHandle (sizeof (widpt))); 
Width**.h := 2; { denominator is 2} 
Width**’.v := 7; { numerator is 7} 


myPic := OpenPicture (theWorld) ; 
SetPen(1,2); { Set the pen size to 1 wide x 2 high } 
ClipRect (theWorld) ; 
MoveTo (20,20); 
DrawString('Do line test"); 
PicComment (DashedLine, GetHandleSize (Handle (dashedln) ) , Handle (dashedin)); 
PicComment (Set LineWidth, 4, Handle (width) } ; {SetLineWidth} 
SetRect (arect,100,100,500,500); 
FrameRect (aRect) ; 
MoveTo (500,500); 
Lineto (100,100); 


PicComment (DashedStop,0,nil); {DashedStop] 
ClosePicture; 
DisposHandle (handle (width) ); {Clean up} 
DisposHandle (handle (dashedIin) ) ; 
PrintThePicture; {print it please} 


KillPicture (MyPic) ; 
End; {LineTest } 


PostScript Commands 


The PostScript comments tell the printer driver that the application is going to be 
communicating with the LaserWriter directly using PostScript commands instead of 
QuickDraw. The driver sends the accompanying PostScript to the printer with no 
preprocessing and no error checking. The application can specify data in the comment 
handle itself or point to another file which contains text to send to the printer. When the 
application is finished sending PostScript, the PostScriptEnd comment tells the 
printer driver to resume normal QuickDraw mode. 


There are some guidelines you need to remember: 


° The graphic state set up during QuickDraw calls is maintained 
and is not atfected by PostScript calls made with these comments. 


e The header has changed a number of parameters so sometimes you won't get the 
results you expect. You may want to take a look at the header listed in The 
LaserWriter Reference Manual available through APDA. 


«The header changes the PostScript coordinate system so that the origin is at the 
top-left corner of the page instead of at the bottom-left corner. This is done so that the 
QuickDraw coordinates that are used don’t have to be constantly remapped into the 
standard PostScript coordinate system. If you don’t change this, al! drawing is printed 
upside down. Please see the PostScript Language Reference Manual for more details 
about transformation matrices. 
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* Don't call ShowPage. This is done for you by the driver. If you do call this you will not 
be able to switch back to QuickDraw mode and an additional page will be printed 
when you call PrClosePage. 


¢ Don't call ExitServer. You may get very strange results. 
e Don't call 1initGraphics. Graphics states are already set up by the header. 
¢ Don't do anything that you expect to live across jobs. 


e You won't be able to interrogate the printer and get information back through the 
driver. 


The PostScriptBegin comment sets the driver state to prepare for the generation of 
PostScript by the application by calling gsave to save the current state. PostScript is 
then sent to the printer by using comments 192 through 195. The QuickDraw state of 
the driver is then restored by the PostScriptEnd comment. All QuickDraw operations 
that occur outside of these comments are performed; no clipping occurs as with the text 
rotation comments. 


PostScript From a Text Handle 


When the PostScriptHandle comment is used, the handie pSData points to the 
PostScript commands which are sent. PSData isa generic handle that points to text, 
without a length byte. The text is terminated by a carriage return. This comment is 
terminated by a PostScriptEnd comment. 


Note: Due to a bug in the 3.1 LaserWriter driver, PostScriptEnd will not restore the 
QuickDraw state after the use of a Post ScriptHandle comment. The workaround is 
to only use this comment at the end of your drawing, after you have made all the 
QuickDraw calls you need. This problem will be fixed in the next version of the driver. 


Here’s an example of how to use this comment: 


Procedure PostHdl; 
{ this procedure shows how to use PostScript from a text Handle} 


CONST 
PostScriptBegin = 190; 
PostScriptEnd = 191; 
PostScriptHandle = 192; 


VAR 
myString : Str255; 
tempstr : String[1]; 
MyHandle : Handle; 
err : OSErr; 


BEGIN { PostHdl } 

MyString := '/Times-Roman findfont 12 scalefont setfont 230 600 moveto 
(Hello World) show'; 

tempstr:=' '; 
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tempstr(1] := chr(13); {has to be terminated by a carriage return } 
MyString := Concat (mystring,tempstr); { in order for it to execute] 
err := PtrToHand (Pointer(ord(@myString)+1),MyHandle, length (MyString) }; 
MyPic := OpenPicture (theWorld); 

ClipRect (theWorld); 

MoveTo (20,20); 

DrawString('PostScript from a Handle'); 


PicComment (PostScriptBegin,0,nil); {Begin PostScript} 
PicComment (PostScriptHandle, length (mystring) ,MyHandle) ; 
PicComment (PostScriptEnd,0,nil); {PostScript End} 
ClosePicture; 
DisposHandle (MyHandle) ; {Clean up} 
PrintThePicture; {print it please} 


KillPicture (MyPic) ; 
End; { PostHdl } 


Defining PostScript as QuickDraw Text 


All QuickDraw text following the Text IsPostScript comment is sent as PostScript. 
No error checking is performed. This comment is terminated by a PostScriptEnd 
comment. 


Here is an example: 


Procedure PostText; 
{Shows how to use PostScript in strings in a QuickDraw picture} 


CONST 
PostScriptBegin = 190; 
PostScriptEnd = 191; 
TextIsPostScript = 194; 


Begin { PostTest } 
MyPic := OpenPicture (theWorld) ; 
ClipRect (theWorld) ; 
MoveTo (20,20) ; 
DrawString('TextIsPostScript Comment"); 


PicComment (PostScriptBegin,0,nil); {Begin PostScript} 

PicComment (TextIsPostScript,0,nil); {following text is PostScript} 
DrawString('0 728 translate‘); {move the origin and rotate the} 
DrawString('l -1 scale"); {coordinate system} 


DrawString ('newpath'); 
DrawString('100 470 moveto'); 
DrawString('500 470 lineto'); 
DrawString('100 330 moveto'); 
DrawString('500 330 lineto'); 
DrawString('230 600 moveto"); 
DrawString('230 200 lineto’); 
DrawString('370 600 moveto'); 
DrawString('370 200 lineto’); 
DrawString('10 setlinewidth'); 
DrawString('stroke'); 
DrawString('/Times-Roman findfont 12 scalefont setfont'); 
DrawString('230 600 moveto'); 
DrawString(' (Hello World) show'); 
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PicComment (PostScriptEnd, 0,nil); {PostScriptEnd} 
ClosePicture; 
PrintThePicture; {print it please} 
Killpicture (MyPic) ; 
End; { PostText } 


PostScript From a File 


The PostScriptFile and ResourcePS comments allow you to send PostScript to the 
printer from a resource file. Before these comments are described there are some 
restrictions you need to follow: 


«Don’t ever copy a picture containing these comments to the clipboard. If it is pasted 
into another application and the specified file or resource is not available, printing will 
be aborted and the user won’t know what went wrong. This could be very confusing 
to a user. If you want the PostScript information to be available when printed from 
another application, use one of the other comments and include the information in the 
picture. 


* Don't keep the PostScript in a separate file from the actual data file. If the data file 
ever gets moved without the PostScript file, when the picture is printed the data file 
may not be found and the print job will be aborted, again without the user knowing 


what went wrong. Keeping the data and PostScript in the same file will forestall many 
headaches for you and the user. 


Now, a description of the comments: 


The PostScriptFile comment tells the driver to use the POST type resources 
contained in the file FileNameString. FileNamest ring is declared as a Str255. 


When this comment is encountered, the driver calls OpenResFile using the file name 
specified in FileNameString. It then calls GetResource ('posT',thelID); 
repeatedly, where theID begins at 501 and is incremented by one for each 
GetResource Call. If the driver gets a ResNotFound error, it closes the specified 
resource file. If the first byte of the resource is a 3, 4, or 5 then the remaining data is 
sent and the file is closed. 


The format of the POST resource is as follows: The IDs of the resources start at 501 
and are incremented by one for each resource. Each resource begins with a 2 byte 
data field containing the data type in the first byte and a zero in the second. The 
possible values for the first byte are: 


ignore the rest of this resource (a comment) 

data is ASCII text 

data is binary and is first converted to ASCII before being sent 

AppleTalk end of file. The rest of the data, if there is any, is interpreted as ASCII text 
and will be sent after the EOF. 

open the data fork of the current resource file and send the ASCII text there 

end of the resource file 


on e wh —-+ © 


The second byte of the field must always be zero. Resources should be kept small, 
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around 2K. Text and binary should not be mixed in the same resource. Make sure you 
include either a space or a return at the end of each PostScript string to separate it from 
the following command. 


Here’s an example: 


PROCEDURE PostFile; 
{ This procedure shows how to use PostScript from a specified FILE} 


CONST 
PostScriptBegin = 190; 
PostScriptFile = 193; 
PostScriptEnd = 191; 


VAR 
MyString ¢ Str255; 
MyHandie : Handle; 
err s OSErr; 
BEGIN {-PostFile } 


{You should never do this in a real program. This is only a test.} 
MyString := "HardDisk:MPW:Print Examples:PSTestDoc'; 
err := PtrToHand (pointer (MyString) ,MyHandle, length (MyString) + 1); 
MyPic := OpenPicture (theWorld) ; 
ClipRect (theWorld) ; 
MoveTo (20,20); 
DrawString('PostScriptFile Comment') ; 
PicComment (PostScriptBegin,0,nil); {Begin PostScript} 
PicComment (PostScriptFile, GetHandleSize (MyHandle) ,MyHRandle) ; 
PicComment (PostScriptEnd,0,nil); {PostScriptEnd} 
MoveTo (50,50); 
DrawString('PostScriptEnd has terminated’); 
ClosePicture; 
DisposHandle (MyHandle); {Clean up} 
PrintthePicture; {print it please} 
KillPicture (MyPic); 
END; { PostFile } 


Here are the resources: 


type 'POST' { 


switch { 

case Comment: /* this is a comment */ 
key bitstring[8] = 0; 
fill byte; 
string; 

case ASCII: /* This is just ASCII text */ 
key bitstring[8] = 1; 
fill byte; 
string; 

case Bin: /* This is binary */ 
key bitstring[8] = 2; 
fill byte; 
string; 
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case ATEOF: /* This is an AppleTalk EOF */ 


key bitstring[8] = 3; 


fill byte; 
string; 
case DataFork: /* send the text in the data fork */ 
key bitstring[8] = 4; 
fill byte; 
case EOF: /* no more */ 
key bitstring[8] = 5; 
fill byte; 


}3 


resource 'POST’ (501) { 
ASCII{"0 728 translate "}}; 


resource "POST' (502) { 
ASCII{"1 -1 scale "}}; 


resource 'POST' (503) { 
ASCII{"newpath "}}; 


resource ‘POST’ (504) { 
ASCII{"100 470 moveto ™}}; 


resource 'POST' (505) { 
ASCII{"500 470 lineto ™"}}; 


resource 'POST' (506) { 
ASCII{"100 330 moveto "}}; 


resource 'POST' (507) { 
ASCII{"500 330 lineto "}}; 


resource ‘POST’ (508) { 
ASCII{"230 600 moveto "}}; 


resource 'POST' (509) { 
ASCII{"230 200 lineto ™"}}; 


resource ‘POST’ (510) { 
ASCII{"370 600 moveto "™}}; 


resource 'POST' (511) { 
ASCII{"370 200 lineto "}}; 


resource ‘POST’ (512) { 
ASCII{"10 setlinewidth "}}; 


resource ‘POST’ (513) { 
ASCII{"stroke "™}}; 


resource ‘'POST' (514) { 
ASCII{"/Times-Roman findfont 12 scalefont setfont "}}; 
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resource ‘POST'S (515) { 
ASCII{"230 600 moveto "}}; 


resource 'POST' (516) { 
ASCII({(" (Hello World) show "}}; 


/* It will stop reading and close the file after 517 */ 
resource 'POST' (517) { 

EOF 

{}}7 


/* it never gets here */ 
resource '"POST' (518) { 
DataFork 

{}}; 


When the ResourcePsS comment is encountered, the LaserWriter driver sends the text 
contained in the specified resource as PostScript to the printer. The additional data is 
defined as 


PSRsre = record 
PSType : Restype; 
PSID : Integer; 
PSIndex: Integer; 


The resource can be of type STR or STR#. If the Type is STR then the index should 
be 0. Otherwise an index should be given. 


This comment is essentially the same as the PrintF contro! call to the driver. The 
imbedded command string it uses is **r*n', which basically tells the driver to send the 
string specified by the additional data, then send a newline. For more information 
about printer control calls see the LaserWriter Reference Manual. 


Here’s an example: 


PROCEDURE PostRSRC; 
{ This procedure shows how to get PostScript from a resource FILE} 


CONST 
PostScriptBegin = 190; 
PostScriptEnd = 191; 
ResourcePS = 195; 


TYPE 
theRSRChdl = “theRSRCptr; 
theRSRCptr = “theRSRC; 
theRSRC = RECORD 
theType: ResType; 
theID: integer; 
Index: integer; 
END; 


VAR 
temp : Rect; 
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TheResource : theRSRChdl; 


P : integer; 
myport < GrafPtr; 
err : integer; 
atemp : Boolean; 
BEGIN { PostRSRC } 


TheResource := theRSRChdl (NewHandle (SizeOf (theRSRC) )); 
TheResource**.theID := 500; 
TheResource**.Index := 0; 
TheResource’**.theType := ‘STR '; 
HLock (Handle (TheResource) ) ; 
MyPic := OpenPicture (theWorld) ; 
DrawString('ResourcePS Comment'); 
PicComment (PostScriptBegin,0,nil}; {Begin PostScript} 
PicComment (ResourcePS, 8, Handle (TheResource)); {Send postscript} 
PicComment (PostScriptEnd,0,nil); {(PostScriptEnd} 
ClosePicture; 
DisposHandle (Handle (TheResource)); {Clean up} 
PrintthePicture; {print it please} 
KillPicture (MyPic) ; 

END; { PostRSRC } 


Here’s the resource: 


resource ‘STR ' (500) 

{"0 728 translate 1 -1 scale newpath 100 470 moveto 500 470 lineto 100 330 
moveto 500 330 lineto 230 600 moveto 230 200 lineto 370 600 moveto 370 200 
lineto 10 setlinewidth stroke /Times-Roman findfont 12 scalefont setfont 230 
600 moveto (Hello World) show" 

}3 


Rotation 


The concept of rotation doesn’t apply to text alone. PostScript can rotate any object. 
The rotation comments work exactly like text rotation except that all objects drawn 
between the two comments are drawn in the rotated coordinate system specified by the 
center of rotation comment, not just text. Also, no clipping of CopyBits calls occurs. 
These comments only work on the 3.1 LaserWriter driver. 


The RotateBegin comment tells the driver that the following objects will be drawn in a 
rotated plane. This comment contains the following data structure: 


Rotation = Record 
Flip: Integer; {0,1,2 => none, horizontal, vertical coordinate flip } 
Angle: Integer; {0..360 => clockwise rotation in degrees } 

End; { Rotation } 


When you are finished, the RotateEnd comment returns the coordinate system to 
normal, terminating the rotation. 


The relative center of rotation is specified by the RotateCenter comment in exactly 
the same manner as the TextCenter comments. The difference, however, is that 
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this comment must appear before the RotateBegin comment. The data structure 
of the accompanying handle is exactly like that for the TextCenter comment. 


Here’s an example of how to use rotation comments: 


Procedure Test; 
{This procedure shows how to do rotations} 


CONST 
RotateBegin = 200; 
RotateEnd = 201; 
RotateCenter = 202; 


TYPE 

rothdl = “rotptr; 

rotptr = “trot; 

trot = Record 

flip : integer; 
Angle : integer; 

End; { trot )} 

centhdl = “centptr; 

centptr = “cent; 

Cent = packed Record 
yint: Integer; 
yFrac: Integer; 
xInt: Integer; 
xFrac: Integer; 

End; { Cent } 


VAR 
arect >: rect; 
rotation : rothdl; 
center : centhdl; 


Begin { Test } 
rotation := rothdl (NewHandle (sizeof (trot))); 


rotation^^.flip := 0; {no flip} 
rotation**.angle := 15; {15 degree rotation} 

center := centhdl (NewHandle (sizeof (cent) )); 

center**.xInt := 50; {center at 50,50} 
center**.yInt := 50; 

center’*.xFrac := 0; {no fractional part} 
center^^.yFrac := 0; 


myPic := OpenPicture (theWorld) ; 
ClipRect (theWorld); 
MoveTo (20,20); 
DrawString('Begin Rotation"); 


{set the center of Rotation} 

PicComment (RotateCenter, GetHandleSize (Handle (center) ), Handle (center) ) ; 
{Begin Rotation} 
PicComment (RotateBegin, GetHandleSize (Handle (rotation) ) ,Handle (rotation) ); 
SetRect (arect,100,100,500,500); 

FrameRect (aRect);? 

MoveTo (500, 500) ; 
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Lineto (100,100); 


PicComment (RotateEnd,0,nil); {RotateEnd} 
ClosePicture; 
DisposHandle (handle (rotation) ); {Clean up} 
DisposHandle (handle (center) ); 
PrintThePicture; {print it please} 


KillPicture (MyPic) ; 
End; { Test } 


Printing Forms 


The two form printing comments allow you to prepare a template to use for printing. 
When the FormsBegin comment is used, the LaserWriter’s buffer is not cleared after 
PrClosePage. This allows you to download a form then change it for each subsequent 
page, inserting the information you want. FormsEnd allows the buffer to be cleared at 
the next PrClosePage. 
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Macintosh Technical Notes C3 


#93: MPW: {$LOAD} ;_ Datalnit; % _MethTables 


See also: MPW Reference Manuals 
Written by: Jim Friedlander November 15, 1986 
Modified by: Jim Friedlander January 12, 1987 


This technical note discusses the Pascal {SLOAD} directive as well as how 
to unload the DataInit and % MethTables segments. This revision 
enhances the discussion about unloading % MethTables. 


{$LOAD} 
MPW Pascal has a {SLOAD} directive that can dramatically speed up compiles. 
{SLOAD HD:MPW:PLibraries:PasSymDump} 


will combine symbol tables of all units following this directive (until another {$LOAD} 
directive is encountered), and dump them out to HD: MPW:PLibraries:PasSymDump. 
In order to avoid using fully specified pathnames, you can use {$LOAD} in conjunction 
with the -k option for Pascal: 


Pascal -k "{PLibraries}" myfile 
combined with the following lines in myfile: 


USES 
{$LOAD PasSymDump} 
MemTypes,QuickDraw, OSIntf, Toolintf, PackIntf, 
{SLOAD} {This “turns off” SLOAD for the next unit} 
NonOptimized, 
{SLOAD MyLibDump } 
MyLib; 


will do the following: the first time a program containing these lines is compiled, two 
symbol table dump files (in this case PasSymDump and MyLibDump) will be created in 
the directory specified by the -k option (in this case (PLibraries}).No dump file will 
be generated for the unit NonOptimized. The compiler will compile MemTypes, 
QuickDraw, OSIntf, Toolintf, PackIntf (quite time consuming) and dump those 
units’ symbols to PasSymDump and it will compile the interface to MyLib and dump its 
symbols to MyLib. For subsequent compiles of this program (or any program that uses 
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ne same dump file(s)), the interface files will not be recompiled, the compiler will 
simply read in the symbol table. 


Compiling a sample five line program on a Macintosh Plus/HD20SC takes 62 seconds 
without using the {SLOAD} directive. The same program takes 10 seconds to compile 
using the {SLOAD} directive (once the dump file exists). For further details about this 
topic, please see the MPW Pascal Reference Manual (Final Draft, p. 150). 


Note: If any of the units that are dumped into a dump file change, you need to make 
sure that the dump file is deleted, so that it can be regenerated by the Pascal compiler 
with the correct information. The best way to do this is to use a makefile to check the 
dump file against the files it depends on, and delete the dump file if it is out of date with 
respect to any of the units that it contains. An excellent (and well commented) example 
of doing this is in the MPW Workshop Manual (Final Draft, pp. 7-20 through 7-22). 


The Datalnit Segment 


The Linker will generate a segment whose resource name is tA5Init for any program 
compiled by the C or Pascal compilers. This segment is called by a program’s main 
segment. This segment is loaded into the application heap and locked in place. It is up 
to your program to unload this segment (otherwise, it will remain locked in memory, 
possibly causing heap fragmentation). To do this from Pascal, use the following lines: 


PROCEDURE _DataInit; EXTERNAL; 


BEGIN {main PROGRAM} 
UnloadSeg (@_DataInit) ; 
{remove data initialization code before any allocations} 


From C, use the following lines: 


extern DataInit(); 


{ /* main */ 
UnloadSeg(_ DataInit); 
/*remove data initialization code before any allocations*/ 


For further details about Data Initialization, see Appendix | of the MPW Reference 
Manual (Final Draft). 


% MethTables and % SelProcs 


Object use in Pascal produces two segments which can cause heap problems. These 
are % MethTables and % SelProcs which are used when method calls are made. 
MacApp deals with them correctly, so this only applies to Object Pascal programs that 
don’t use MacApp. You can make the segments locked and preloaded (probably the 
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szasiest route), so they will be loaded low in the heap, or you can unload them 
temporarily while you are doing heap initialization. In the latter case, make sure there 
are no method calls while they are unloaded. To reload % MethTables and 
% SelProcs, Call the dummy procedure %_InitObj. %_InitOb] loads tMethTables 
—calling any method will then load § SelProcs. 


Reminder: The linker is case sensitive when dealing with module names. Pascal 
converts all module names to upper-case (unless a routine is declared to be a C 
routine). The Assembler default is the same as the Pascal default, though it can be 
changed with the CASE directive. C preserves the case of module names (unless a 
routine is declared to be pascal, in which case the module name is converted to 
upper- case letters). 


Make sure that any external routines that you reference are capitalized the same in 
both the external routine and the externa! declaration (especially in C). If the 
capitalization differs, you will get the following link error (library routine = findme, 
program declaration = extern FindMe () ;): 


### Link: Error Undefined entry, name: FindMe 
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#96: SCSI Bugs 


see also: The SCSI Manager 

SCSI Developer's Package (APDA) 
Written by: Steve Flowers October 1, 1986 
Modified by: Bryan Stearns November 15, 1986 
Modified by: Bo3b Johnson July 1, 1987 


There are a number of problems in the Macintosh Plus SCSI Manager; this 
note lists the ones we know about, along with an explanation of what we're 
doing about them. Changes since 11/86 include information on fixes in 
system file 4.1. 


There are several categories of SCSI Manager problems: 


1. Those in the ROM boot code 

(Before the System file has been opened, and hence, before any patches could possibly 
fix them.) 

2. Those that have been fixed in System 3.2 

3. Those that have been fixed in System 4.1 

4. Those that are new in System 4.1 

5. Those that have not yet been fixed. 


The problems in the ROM boot code can only be fixed by changing the ROMs. Most of 
the bugs in the SCSI Manager itself have been fixed by the patch code in the System 3.2 
file. There are a few problems, though, that are not fixed with System 3.2—most of these 
bugs have been corrected in System 4.1. Any that are not fixed will be detailed here. 
ROM code for future machines will, of course, include the corrections. 


ROM boot code problems 


¢ In the process of looking for a bootable SCSI device, the boot code issues a SCSI 
bus reset before each attempt to read block O from a device. If the read fails for any 
reason, the boot code goes on to the next device. SCSI devices which implement the 
Unit Attention condition as defined by the Revision 17B SCSI standard will fail to 
boot in this case. The read will fail because the drive is attempting to report the Unit 
Attention condition for the first command it receives after the SCSI bus reset. The 
boot code does not read the sense bytes and does not retry the failed command; it 
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simply resets the SCSI bus and goes on to the next device. If no other device is 
bootable, the boot code will eventually cycle back to the same SCSI device ID, reset 
the bus (causing Unit Attention in the drive again), and try to read block 0 (which 
fails for the same reason). 


The ‘new’ Macintosh Plus ROMs that are included in the platinum Macintosh Plus 
have only one change. The change was to simply do a single SCSI Bus Reset after 
power up instead of a Reset each time through the SCSI boot loop. This was done to 
allow Unit Attention drives to be bootable. It was an object code patch (affecting 
approximately 30 bytes) and no other bugs were fixed. For details on the three 
versions of Macintosh Plus ROMs, see Technical Note #154. 


We recommend that you choose an SCSI controller which does not require the Unit 
Attention feature—either an older controller (most of the SCSI! controllers currently 
available were designed before Revision 17B), or one of the newer 
Revision-17B-compatible controllers which can enable/disable Unit Attention as 
a formatting option (such as those from Seagate, Rodime, et al). Since the vast 
majority of Macintosh Plus computers have the ROMs which cannot use Unit 
Attention drives, we still recommend that you choose an SCSI controller that does 
not require the Unit Attention feature. 


¢ If an SCSI device goes into the Status phase after being selected by the boot code, 
this leads to the SCSI bus being left in the status phase indefinitely, and no SCSI 
devices can be accessed. The current Macintosh Plus boot code does not handle 
this change to Status phase, which means that the presence of an SCSI device with 
this behavior (as in some tape controllers we’ve seen) will prevent any SCSI devices 
from being accessed by the SCSI Manager, even if they already had drivers loaded 
from them. The result is that any SCSI peripheral that is turned on at boot time must 
not go into Status phase immediately after selection; otherwise, the Macintosh Plus 
SCSI bus will be left hanging. Unless substantially revised ROMs are released for 
the Macintosh Plus (highly unlikely within the next year or so), this problem will never 
be fixed on the Macintosh Plus, so you should design for old ROMs. 


e The Macintosh Plus would try to read 256 bytes of blocks 0 and 1, ignoring the extra 
data. The Macintosh SE and Macintosh II try to read 512 bytes from blocks 0 and 1, 
ignoring errors if the sector size is larger (but not smaller) than 512 bytes. Random 
access devices (disks, tapes, CD ROMS, etc.) can be booted as long as the blocks 
are at least 512 bytes, blocks 0, 1 and other partition blocks are correctly set up, and 
there is a driver on it. With the new partition layout (documented in Inside Macintosh 
volume V), more than 256 bytes per sector may be required in some partition map 
entries. This is why we dropped support for 256-byte sectors. Disks with tag bytes 
(532-byte sectors) or larger block sizes (1K, 2K, etc.) can be booted on any Macintosh 
with an SCSI port. Of course, the driver has to take care of data blocking and 
de-biocking, since HFS likes to work with 512-byte sectors. 


Problems with ROM SCSI Manager routines 


Note that the following problems are fixed after the System file has been opened; for a 
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device to boot properly, it must not depend on these fixes. The sample SCSI driver, 
available from APDA, contains an example of how to find out if the fixes are in place. 


Prior to System file 3.2, blind transfers (both reads and writes) would not work 
properly with many SCSI controllers. Since blind operation depends on the drive’s 
ability to transfer data fast enough, it is the responsibility of the driver writer to make 
sure blind operation is safe for a particular device. 


Prior to System file 3.2, the SCSI Manager dropped a byte when the driver did 
two or more SCSIReads Or SCSIRBlinds ina row. (Each Read Or RBlind has to 
have a Transfer Information Block (TIB) pointer passed in.) The TIB itself can be as 
big and complex as you want—it is the process of returning from one SCSIRead or 
SCSIRBlind and entering another one (while still on the same SCS! command) that 
causes the first byte for the other ScSIReads to be lost. 


Note that this precludes use of file-system tags. Apple no longer recommends that 
you support tags; see Technical Note #94 for more information. 


Prior to System file 3.2, scsIStat didn't work; the patched version now works 
correctly. 


Running under System file 3.2, the SCSI Manager does not check to make sure 
that the last byte of a write operation (to the peripheral) was handshaked while 
operating in pseudo-DMA mode. The SCSI Manager writes the final byte to the NCR 
5380’s one-byte buffer and then turns pseudo-DMA mode off shortly thereafter 
(reported to be 10-15 microseconds). If the peripheral is somewhat slow in actually 
reading the last byte of data, it asserts REQ after the Macintosh has already turned off 
pseudo-DMA mode and never gets an Ack. The CPU then expects to go into the 
Status phase since it thinks everything went OK, but the peripheral is still waiting for 
ack. Unless the driver can recover from this somehow, the SCSI bus is ‘hung’ in the 
Data Out phase. In this case, all successive SCSI Manager calls will fail until the 
bus is reset. 


Running under System file 4.1, the SCSI Manager waits for the last byte of a 
write operation to be handshaked while operating in pseudo-DMA mode; it checks for 
a final DRQ (or a phase change) at the end of a SCcSIWrite or SCSIWBlind before 
turning off the pseudo-DMA mode. Drivers that could recover from this problem by 
writing the last byte again if the bus was still in a Data Out phase will still work 
correctly, as long as they were checking the bus state. 


Running under System file 3.2, the SCSI Manager does not time out if the 

peripheral fails to finish transferring the expected number of bytes for polled reads 
and writes. (Blind operation does poll for the first byte of each requested data transfer 
in the Transfer Information Block.) 


Running under System file 4.1, ScSIRead and SCSIWrite return an error to the 
caller if the peripheral changes the bus phase in the middle of a transfer, as might 
happen if the peripheral fails to transfer the expected number of bytes. The computer 
is no longer left in a hung state. 
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Running under System file 3.2, the Selection timeout value is very short (900 
microseconds). Patches to the SCSI Manager in System 4.1 ensure that this value 
is the recommended 250 milliseconds. 


Running under System file 3.2, the SCSI Manager routine scsIGet (which 
arbitrates for the bus) will fail if the BSy line is still asserted. Some devices are a bit 
slow in releasing BSy after the completion of an SCSI operation, meaning that BSy 
may not have been released before the driver issues a SCSIGet call to start the next 
SCSI operation. A work-around for this is to call ScSIGet again if it failed the first 
time. (Rarely has it been necessary to try it a third time.) This assumes, of course, 
that the bus has not been left ‘hanging’ by an improperly terminated SCSI operation 
before calling SCSIGet. 


Running under System file 4.1, the scSIGet function has been made more 
tolerant of devices that are slow to release the BSy line after a SCS! operation. The 
SCSI Manager now waits up to 200 milliseconds before returning an error. 


Problems with the SCSI Manager that haven’t been fixed yet 


These problems currently exist in the Macintosh Plus, SE, and II SCSI Manager. We 
plan to fix these problems in a future release of the System Tools disk, but in the mean 
time, you should try to work around the problems (but don’t “require” the problems). 


Multiple calls to ScSIRead of SCSIRBlind after issuing a command and before 
calling SCSIComplete may not work. Suppose you want to read some mode sense 
data from the drive. After sending the command with ScsIcmd, you might want to call 
SCSIRead with a TIB that reads four bytes (typically a header). After reading the field 
(in the four-byte header) that tells how many remaining bytes are available, you might 
call SCSIRead again with a TIB to read the remaining bytes. The problem is that the 
first byte of the second SCSIRead data will be lost because of the way the SCSI 
Manager handles reads in pseudo-DMA mode. A work-around is to issue two 
separate SCSI commands: the first to read only the four-byte header, the second to 
read the four-byte header plus the remaining bytes. It is also possible to use a clever 
TIB that contains two data transfers, the second of which gets the transfer length from 
the first transfer’s received data (the header). This bug will probably not be fixed. 


On read operations, some devices may be slow in deasserting REQ after sending the 
last byte to the CPU. The current SCSI Manager (all machines) will return to the 
caller without waiting for REQ to be deasserted. Usually the next call that the driver 
would make is SCSIComplete. On the Macintosh SE and Il, the scSIcomplete Call 
will check the bus to be sure that it is in Status phase. If not, the SCSI Manager will 
return a new error code that indicates the bus was in Data In/Data Out phase when 
SCSIComplete was called. The combination of the speed of the Macintosh II and a 
slow peripheral can cause SCSIComplete to detect that the bus is still in Data In 
phase before the peripheral has finally changed the bus to Status phase. This 
results in a false error being passed back by ScCSIComplete. 


The scCompare TIB opcode no longer works in System 4.1 on the Macintosh Plus 
only. It returns an error code of 4 (bad parameters). This will be fixed in the next 
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version of the System file. : 


Other SCSI Manager Issues 


¢ At least one third-party SCS! peripheral driver used to issue SCSI commands from a 
VBL task. It didn’t check to see if the bus was in the free state before sending the 
command! This is guaranteed to wipe out any other SCSI command that may have 
been in progress, since the SCSI Manager on the Macintosh Plus does not mask out 
(or use) interrupts. 


We strongly recommend that you avoid calling the SCSI Manager from interrupt 
handlers (such as VBL tasks). If you must send SCSI commands from a VBL task (like 
for a removable media system), do a SCSIStat call first to see if the bus is currently 
busy. If it’s free (BSy is not asserted), then it's probably safe; otherwise the VBL task 
should not send the command. Note that you can’t call scsIstat before the System 
file fixes are in place. Since SCSI operations during VBL are not guaranteed, you 
should check all errors from SCSI Manager calls. 


A new SCSI Manager call will probably be added in the near future. This will be a 
high-level call; it will have some kind of parameter block in which you give a pointer to 
a command buffer, a pointer to your TIB, a pointer to a sense data buffer (in case 
something goes wrong, the SCSI Manager will automatically read the sense bytes into 
the buffer for you), and a few other fields. The SCSI Manager will take care of 
arbitration, selection, sending the command, interpreting the TIB for the data transfer, 
and getting the status and message bytes (and the sense bytes, if there was an error). 
It should make SCSI device drivers much easier to write, since the driver will no longer 
have to worry about unexpected phase changes, getting the sense bytes, and so on. 


® 


The SCSI Manager (all machines) does not currently support interrupt-driven 
(asynchronous) operations. The Macintosh Plus can never support it since there is no 
interrupt capability. The Macintosh SE has a maskable interrupt for IRQ, and the 
Macintosh Il has maskable interrupts for both IRQ and DRQ. Apple is working on an 
implementation of the SCSI Manager that will support asynchronous operations on the 
Macintosh I! and probably on the SE as well. Because the interrupt hardware will 
interact adversely with any asynchronous schemes that are polled, it is strongly 
recommended that third parties do not attempt asynchronous operations until the new 
SCSI Manager is released. Apple will not attempt to be compatible with any products 
that bypass some or all of the SCSI Manager. In order to implement software-based 
(polied) asynchronous operations it is necessary to bypass the SCS! Manager. 


The SCSI Manager section of the alpha draft of Inside Macintosh volume V 
documented the Disconnect and Reselect routines which are used for asynchronous 
I/O. The current implementation of those routines is based on polling and will therefore 
not work in the future when the SCSI Manager becomes interrupt-driven. Those 
routines have been removed from the manual for this reason, and it is strongly 
recommended that those routines not be used. Any software that uses those routines 
will have to be revised when the SCSI Manager becomes interrupt-driven. Drivers 
which send SCSI commands from VBL tasks may also have to be modified. 
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Hardware in the SCSI 


There is some confusion on how many terminators can be used on the bus, and the best 
way to use them. There can be no more than two terminators on the bus. If you have 
more than one SCSI drive you must have two terminators. If you only have one drive, 
you should use a single terminator. If you have more than one drive, the two terminators 
should be on opposite ends of the chain. The idea is to terminate both ends of the wire 
that goes through all of the devices. One terminator should be on the end of the system 
cable that comes out of the Macintosh. The other terminator would be on the very end of 
the last device on the chain. If you have an SE or II with an internal hard disk, there is 
already one terminator on the front of the chain, inside the computer. 


On the Macintosh SE and Il, there is additional hardware support for the SCSI bus 
transfers in pseudo-DMA mode. The hardware makes it possible to handshake the data 
in Blind mode so that the Blind mode is safe for all transfers. On the Macintosh Plus, the 
Blind transfers are heavily timing dependent and can overrun or underrun during the 
transfer with no error generated. Assuring that Blind mode is safe on the Macintosh 
Plus depends upon the peripheral being used. On the SE and Il, the transfer is 
hardware assisted to prevent overruns or underruns. 


Changes in SCSI for SE and Il 


The changes made to the SCSI Manager found in the Macintosh SE and Macintosh I! 
are primarily bug fixes. No new functionality was added. The newer SCSI Manager is 
more robust and has more error checking. Since the Macintosh Plus SCSI Manager 
only did limited error checking, it is possible to have code that would function (with 
bugs) on the Macintosh Pius, but will not work correctly on the SE or Il. The Macintosh 
Plus could mask some bugs in the caller by not checking errors. An example of this is 
sending or receiving the wrong number of bytes in a blind transfer. On the Macintosh 
Plus, no error would be generated since there was no way to be sure how many bytes 
were sent or received. On the SE and Il, if the wrong number of bytes are transferred an 
error will be returned to the caller. The exact timing of transfers has changed on the SE 
and Il as well, since the computers run at different speeds. Devices that are unwittingly 
dependent upon specific timing in transfers may have problems on the newer 
computers. To find problems of this sort it is usually only necessary to examine the error 
codes that are passed back by the SCSI Manager routines. The error codes will 
generally point out where the updated SCSI Manager found errors. 


To report other bugs or make suggestions 
Please send additional bug reports and suggestions to us at the address in Technical 
Note #0. Let us know what SCSI controller you’re using in your peripheral, and whether 


you've had any particularly good or bad experiences with it. We'll add to this note as 
more information becomes available. 
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#101: CreateResFile and the Poor Man’s Search Path 
See also: The File Manager 
The Resource Manager 
Technical Note #77—HFS Ruminations, p. 4 


Written by: Jim Friedlander January 12, 1987 





TT 


CreateResFile checks to see if a resource file with a given name exists, 
and if it does, returns a dupFNErr (-48) error. Unfortunately, to do this 
check, CreateResFile uses a Call that follows the Poor Man’s Search Path 
(PMSP). 





CreateResFile checks to see if a resource file with a given name exists, and if it does, 
returns a dupFNErr (—48) error. Unfortunately, to do the check, CcreateResFile calls 
PBOpenRF, which uses the Poor Man’s Search Path (PMSP). For example, if we have 
a resource file in the System folder named ‘MyFile’ (and no file with that name in the 
current directory) and we call CreateResFile('MyFile'), ResError will return a 
dupFNErr, since PBOpenRF will search the current directory first, then search the 
blessed folder on the same volume. This makes it impossible to use CreateResFile to 
create the resource file ‘MyFile’ in the current directory if a file with the same name 
already exists in a directory that’s in the PMSP. 


To make sure that CreateResFile will create a resource file in the current directory 
whether or not a resource file with the same name already exists further down the 
PMSP, call_Create (PBCreate or Create) before calling createResFile: 


err:= Create ('MyFile',0,myCreator,myType) ; 

{0 for VRefNum means current volume/directory} 
CreateResFile('MyFile'); 
err:= ResError; {check for error} 


This works because Create does not use the PMSP. If we already have ‘MyFrile’ in 
the current directory, Create will fail with a dupFNErr, then, if ‘MyFile’ has an empty 
resource fork, CreateResFile will write a resource map, otherwise, CreateResFile 
will return dupFNErr. If there is no file named ‘MyFile’ in the current directory, 
_Create will create one and then CreateResFile will write the resource map. 


Notice that we are intentionally ignoring the error from Create, since we are calling it 
only to assure that a file named ‘MyFile’ does exist in the current directory. 
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Please note that SFPutFile does not use the PMSP, but that FSDelete does. 
SFPutFile returns the vRefNum/WDRefNun of the volume/folder that the user selected. 
lf your program deletes a resource file before creating one with the same name based 
on information returned from SFPutFile, you can use the following strategy to avoid 
deleting the wrong file, that is, a file that is not in the directory specified by the 
vRefNum/WDRefNum returned by SFPutFile, but in some other directory in the PMSP: 


VAR 
wher : Point; 
reply : SFReply; 
err : OSErr; 


wher.h := 80; wher.v := 90; 
SFPutFile(wher,'','',NIL, reply); 
IF reply.good THEN BEGIN 
err := GetVol(NIL,oldVol); {So we can restore it later} 
err := SetVol(NIL, reply.vRefNum) ;{for the CreateResFile call} 


{Now for the Create/CreateResFile calls to create a resource file that 
we know is in the current directory} 


err := Create (reply. fName, reply. vRefNum, myCreator, myType) ; 
CreateResFile(reply.fName); {we'll use the ResError from this ...} 


CASE ResError OF 
noErr: {the create succeeded, go ahead and work with the new 
resource file -- NOTE: at this point, we don’t know 
what’s in the data fork of the file!!} ; 
dupFNErr: BEGIN {duplicate file name error} 
{the file already existed, so, let's. delete it. We're now 
sure that we're deleting the file in the current directory} 


err:= FSDelete(reply.fName, reply.vRefNum) ; 


{now that we've deleted the file, let’s create the new one, 
again, we know this will be in the current directory} 


err:= Create (reply .fName, reply. vRefNum, myCreator,myType) ; 
CreateResFile (reply. fName) ; | 
END; {CASE dupFNErr]} 


OTHERWISE {handle other errors} ; 
END; {Case ResError} 
END; {If reply.good} 


Note: OpenResFile uses the PMSP too, so you may have to adopt similar strategies 
to make sure that you are opening the desired resource file and not some other file 
further down the PMSP. This is normally not a problem if you use SFGetFile, since 
SFGet File does not use the PMSP, in fact, sFGet File does not open or close files, so 
it doesn’t run into this problem. 
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#102: HFS Elucidations 


See also: Inside Macintosh Volume 4, File Manager 
Technical Note #77—HFS Ruminations 


Written by: Bryan “Bo3b” Johnson January 12, 1987 


This technical note will describe a few problems that can occur while using 
the Macintosh File System. It will also describe ways to avoid these 
problems. 


This technical note will discuss the following problems: 


1) It is very important to be careful about how files are opened and closed. There must 
be no more than one close for every open. 


2) Don't use Driver names, like .Bout, .Print or .Sony in place of file names or the 
file system will become confused. 


3) Be aware of the ioFlVersNum byte in all file calls. A number of pieces of the 
Macintosh system do not use, and may in fact ignore, files created with non-zero 
ioF1VersNums. 


Each of these problems can lead to strange occurrences, as well as problems for the 
users. Doing any or all of these marginally illegal operations will not necessarily lead 
to a System Error. In some cases the confusion as to what is going on may be worse 
than a System Error. 


One Close is always enough 


If a file is closed twice, it is possible to corrupt the file system on a disk. If a program 
has been creating unreadable disks, this may be the cause. 


One aspect of the file system that is not well documented is how it allocates access 
paths to files that are currently open. As a result of this, it is possible to get a rather 
cavalier attitude about opening and closing files. This discussion will explain why it is 
necessary to be very careful about opening and closing files. 


When the File Manager receives an Open call, it will look at the parameters passed in 
the parameter block and create a new access path for the file that is being opened. 
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The access path is how the File Manager keeps track of where to send data that is 
written, and where to get data that is read from that file. An access path is nothing 
more than: 1) a buffer that the file system uses to read and write data, and 2) a File 
Control Block that describes how the file is stored on a disk. A call like: 


ErrStuff := FSOpen ('FirstFile', theVRefNum, FirstRefNum) ; 
will create the access path as a buffer and a File Control Block (FCB) in the FCB queue. 


Note: The following information is here for illustrative purposes only; dependence on 
it may cause compatibility problems with future system software. 


The structure of the queue can be visualized as: 


FCBSPtr ($34E) ——<—> 0 Buffer Length 
2 
First FCB Record 


2+FCBLength 


Second FCB Record 


Last FCB Record 


where FCBSPtr is a low-memory global (at $34) that holds the address of a 
nonrelocatable block. That block is the File Control Block buffer, and is composed of 
the two byte header which gives the length of the block, followed by the FCB records 
themselves. The records are of fixed length, and give detailed information about an 
open file. As depicted, any given record can be found by adding the length of the 
previous FCB records to the start of the block, adding 2 for the two byte header; giving 
an offset to the record itself. The size of the block, and hence the number of files that 
can be open at any given time, is determined at startup time. The call to open 
‘PirstFile’ above will pass back the File Reference Number to that file in 
FirstRefNum. This is the number that will be used to access that file from that point 
on. The File Manager passes back an offset into the FCB queue as the RefNum. This 
offset is the number of bytes past the beginning of the queue to that FCB record in the 
queue. That FCB record will describe the file that was opened. An example of a 
number that might get passed back as a RefNumis $1D8. That also means that the 
FCB record is $1D8 bytes into the FCB block. 
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A visual example of a record being in use, and how the RefNun is related is: 





Base IS merely the address of the nonrelocatable block that is the FCB buffer. FcBsPtr 
points to it. The RefNum (a number like $1D8) is added to Base, to give an address in 
the block. That address is what the file system will use to read and write to an open file, 
which is why you are required to pass the RefNum to the PBRead and PBWitte calls. 


since that RefNum is merely an offset into the queue, let’s step through a dangerous 
imaginary sequence and see what happens to a given record in the FCB Buffer. Here’s 
the sequence we will step through: 


ErrStuff := FSOpen ('FirstFile’, theVRefNum, FirstRefNum) ; 

ErrStuff := FSClose ( FirstRefNum ); 

ErrStuff := FSOpen ('SecondFile', theVRefNum, SecondRefNum) ; 

ExrStuff := FSClose ( FirstRefNum ); {the wrong file gets closed!!!} 

{the above line will close ‘SecondFile', not 'FirstFile', which is already 
closed} 


Before any operations: 
the record at $1D8 is not used. 


Base 9 
2 


Baset+tRefNum 
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After the call: 
ErrStuff := FSOpen (‘'FirstFile', theVRefNum, FirstRefNum) ; 
FirstRefNum = $1D8 and the record is in use. 





Base+RefNum feces 


After the call: 
ErrStuff := FSClose (FirstRefNum) ; 
FirstRefNum is still equal to $1D8, but the FCB record is unused. 


Base 0 


Base+RefNum 
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After the call: 
Errstuff := FSOpen ('SecondFile', theVRefNum, SecondRefNum) ; 
SecondRefNum = $1D8, FirstRefNum = $1D8, and the record is reused. 





Base+RefNum Ẹ 


After the call: 
ErrStuff := FSClose (FirstRefNum) ; 
The FirstRefNum = $1D8, SecondRefNum = $1D8, 


the queue element is cleared. This happens, even though FirstFile was already 
closed. Actually, SecondFile was closed: 


Base 0 
2 


Base+RefNum 


Note that the second close is using the old RefNum. The second close will still close a 
file, and in fact will return noErr as its result. Any subsequent accesses to the 
SecondRefNum will return an error, since the file ‘SecondFile’ was closed. The File 
Control Blocks are reused, and since they are just offsets, it is possible to get the same 
file RefNum back for two different files. in this case, FirstRefNum = SecondRefNum 
since ‘FirstFile’ was closed before opening ‘SecondFile’ and the same FCB record 
was reused for ‘SecondFile’. 
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There are worse cases than this, however. As an example, think of what can happen if 
a program were to close a file, then the user inserted an HFS disk. The FCB could be 
reused for the Catalog File on that HFS disk. If the program had a generic error 
handler that closed all of its files, it could inadvertently close “its” file again. If it thought 
“its” file was still open it would do the ciose, which could close the Catalog file on the 
HFS disk. This is catastrophic for the disk since the file could easily be closed in an 
inconsistent state. The result is a bad disk that needs to be reformatted. 


There are any number of nasty cases that can arise if a file is closed twice, reusing an 
old RefNum. A common programming practice is to have an error handler or cleanup 
routine that goes through the files that a program creates and closes them all, even if 
some may already be closed. If an FCB element was not reused, the Close will return 
the expected fnOpnErr. If the FCB had been reused, then the Close could be closing 
the wrong file. This can be very dangerous, particularly for all those paranoid hard disk 
users. 


How to avoid the problem: 
A very simple technique is to merely clear the RefNum after each close. If the variable 
that the program uses is cleared after each close, then there is no way of reusing a 


RefNum in the program. An example of this technique would be: 


ErrStuff := FSOpen (‘'FirstFile', theVRefNum, FirstRefNum); 
ErrStuff := FSClose (FirstRefNum) ; 


FirstRefNum := 0; { We just closed it, so clear our refnum } 
ErrStuff := FSOpen ('SecondFile', theVRefNum, SecondRefNum) ; 
ErrStuff := FSClose (FirstRefNum); { returns an error } 


This makes the second Close pass back an error. In this case, the second close will try 
to close RefNum = 0, which will pass back a fnOpnErr and do no damage. Note: Be 
sure to use 0, which will never be a valid RefNum, since the first FCB entry is beyond 
the FCB queue length word. Don’t confuse this 0 with the 0 that the Resource Manager 
uses to represent the System file. 


Thus, if an error handier were cleaning up possibly open files, it could blithely close ali 
the files it knew about, since it would legitimately get an error back on files that are 
already closed. This is not done automatically, however. The programmer must be 
careful about the opening and closing of files. The problem can get quite complex if an 
error is received halfway through opening a sequence of ten files, for example. By 
merely clearing the RefNum that is stored after each close, it is possible to avoid the 
complexities of trying to track which files are open and which are closed. 


This .file name looks outrageous. 


There is a potential conflict between file names and driver names. if a file name is 
named something like .Bout, .Print or .Sony, then the file system will open the 


Technical Note #102 page 6 of7 HFS Elucidations 


driver instead of the file. Drivers have priority on the 128K ROMs, and will always be 
opened before a file of the same name. This may mean that an application will get an 
error back when opening these types of files, or worse, it will get back a driver RefNum 
from the call. What the application thought was a file open call was actually a driver 
open call. If the program uses that access path as a file RefNun, it is possible to get all 
kinds of strange things to happen. For example, if . Sony is opened, the Sony driver's 
RefNum would be passed back, instead of a file RefNum. If the application does a 
Write call using that RefNum, it will actually be a driver call, using whatever 
parameters happen to be in the parameter block. Disks may be searching for new life 
after this type of operation. If a program creates files, it should not allow a file to be 
created whose name begins with *.’. 


This file’s not my type. 


This has been discussed in other places, but another aspect of the File Manager that 
can cause confusion is the ioF1lVersNum byte that is passed to the low-level File 
Manager calls. This is the ioF1lVersNum from Pascal, and ioFileType from 
Assembly. This byte must be set to zero for normal Macintosh files. There are a 
number of parts of the system that will not deal correctly with files that have the wrong 
versions: the Standard File package will not display any file with a non-zero 
ioFlVersNum; the Segment Loader and Resource Manager cannot open files that 
have non-zero ioFlVersNums. It is not sufficient to ignore this byte when a file is 
created. The byte must be cleared in order to avoid this type of problem. Strictly 
speaking, it is not a problem unless a file is being created on an MFS disk. The current 
system will easily allow the user to access 400K disks however, so it is better to be safe 
than confused. 
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#103: Using MaxApplZone and _MoveHHi from Assembly Language 


See also: Using Assembly Language 
The Memory Manager 


Written by: Bryan “Bo3b” Johnson January 12, 1987 


ed 


When calling MaxApplZone and MoveHHi from assembly language, be 
sure to get the correct code. 


_MaxApplZone and MoveHHi were marked [Not in ROM] in Inside Macintosh, 
Volumes I-lll. They are ROM calls in the 128K ROM. Since they are not in the 64K 
ROM, it is necessary to call the routines by a JSR to a glue (library) routine instead of 
using the actual trap macro. The glue calls the ROM routines if they are available, or 
executes its copy of them (linked into your program) if not. 


How to do it: 


Whenever you need to use these calls, just call the library routine. It will check ROM85 
to determine which ROMs are running, and do the appropriate thing. 


In MDS: 
XREF MoveHHi ; we need to use this 'ROM' routine 
JSR MoveHHi : jump to the glue routine that will check ROM85 for us 


and include the Memory .Re1 library in your link file. 


In MPW: 
IMPORT MoveHHi ; we need to use this 
JSR MoveHHi ; jump to the glue routine that will check ROM85 for us 


and link with Interface.o. 


Be sure to avoid calling MaxApplZone Of MoveHHi directly, since that will assemble 
to an actual trap, not to a JSR to the library. 
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#104: MPW: Accessing Globals From Assembly Language 
See also: MPW Reference Manual 


Written by: Jim Friedlander January 12, 1987 


—— O 


This technical note demonstrates how to access MPW Pascal and MPW C 
globals from the MPW Assembler. 





To allow access of MPW Pascal globals from the MPW Assembler, you need to identify 
the variables that you wish to access as external. To do this, use the {$2+} compiler 
option. Using the {$z+} option can substantially increase the size of the object file due 
to the additional symbol information (no additional code is generated and the symbol 
information is stripped by the linker). If you are concerned about object file size, you 
can “bracket” the variables you wish to access as external variables with {$2+} and 
{$Z-}. 


Here’s a trivial example: 


Pascal Source 


Program Test; 


USES 
{SLOAD PasDump.Dump} MemTypes, QuickDraw, OSIntf, Toolintf; 


VAR 
myWRect: Rect; 

{$Z+} {make the following external} 
myInt: Integer; 

{$Z-} {make the following local to this file (not lexically local) } 
err: Integer; 


PROCEDURE MyAsm; EXTERNAL; {Assembly routine that doubles the 
value of myInt)} 


BEGIN {PROGRAM} 
InitGraf (@thePort) ; 


myInt:= 5; 

MyAsm; {call the assy routine, myInt will = 10 now} 

writeln('The value of myInt after calling myAsm =',myInt); 
END. {PROGRAM} 
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The variable myInt is now accessible from assembler. Neither myWRect nor err are 
accessible. If you try to access myWRect, for example, from assembler, you will get the 
following linker error: ### Link: Error Undefined entry name: MYWRECT. 


Assembly Source for Pascal 


CASE OFF ;treat uppercase and lowercase letters identically 
;this is the Assembler’s default 


MyAsm PROC EXPORT 
IMPORT myInt :DATA we need the :DATA otherwise the assembler 
assumes CODE 
multiply by two 
all done with this extensive routine, 


ASL.W  myInt 
RTS 


=, Wwe Fe Se 


whew ! 
END 


C Source 


In an MPW C program, one need only make sure that MyAsm is declared as an external 
function, that myInt is a global variable (capitalizations must match) and that the CASE 
ON directive is used in the Assembler: 


#include <types.h> 
#include <quickdraw.h> 
#include <fonts.h> 
#include <windows.h> 
#include <events.h> 
#include <textedit.h> 
#include <dialogs.h> 
#include <stdio.h> 


extern MyAsm(); /* assembly routine that doubles the value of myInt */ 
short myInt; /* we'll change the value of this variable from MyAsm */ 


main () 

{ 
WindowPtr MyWindow; 
Rect myWRect; 
InitGraf (&qd.thePort) ; 
myint = 5; 
MyAsm(); 


printf("myInt) = %d\n",myint); 
} /*main*/ 
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Assembly source for C 


CASE ON s;treat uppercase and lowercase letters as distinct 
;this is the way C treats uppercase and lowercase letters 


MyAsm PROC EXPORT 
IMPORT myInt:DATA ; we need the :DATA otherwise the assembler 
,; assumes CODE 


ASL.W myiInt ; multiply by two 

RTS ; all done with this extensive routine, 
whew! 

END 
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#105: MPW Object Pascal w.o. MacApp 
See also: Technical Note #93—{$LOAD}; Datalnit;% MethTables 
Written by: Rick Blair January 12, 1987 


Object Pascal must have a CODE segment named % MethTables in order to access 
object methods. In MacApp this is taken care of “behind the scenes” so you don't have 
to worry about it . However, if you are doing a straight Object Pascal program, you must 
make sure that %_MethTables is around when you need it. If it's unloaded when you 
call a method, your Macintosh will begin executing wild noncode and die a gruesome 
and horrible death. 


The MPW Pascal compiler must see some declaration of an object in order to produce 
a reference to the magic segment. You can achieve this cheaply by simply including 
ObjIntf.p in your Uses declaration. This must be in the main program, by the way. 
The compiler will produce a call to * InitObj which is (essentially a Nop) in 
% MethTables. 


If you're a more adventurous soul, you can call % InitObj explicitly from the 
initialization section of your main program (you must use the {$%+} compiler directive 
to allow the use of “$” in identifiers). This will load the % MethTables segment. See 
Technical Note #93 for ideas about locking down segments aa are needed forever 
without fragmenting the heap. 
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#106: The Real Story: VCBs and Drive Numbers 


See also: The File Manager 
Technical Note #36—Drive Queue Element Format 


Written by: Rick Blair January 12, 1987 





EE 


The top of page 178 in Inside Macintosh Volume IV in the File Manager Chapter 
attempts to explain the behavior of two fields in a Volume Control Block when the 
corresponding disk is offline or ejected. Due to the fact that a little bit is left unsaid, this 
paragraph is rather misleading. The two fields in question are vcbDrvNum and 
vcebDRefNum (referred to as ioVDrvInfo and iovDRefNum in C and Pascal). When 
HFS is running, PBHGet VInfo can be used to access these fields. 


Offline 


When a mounted volume is placed offline, vcbDrvNum is cleared and vcbDRefNum is 
set to the two’s complement of the drive number. Since drive numbers are assigned 
positive values (starting with one), this will be a negative number. If vcbDrvNum is zero 
and vcbDRefNum is negative, you know that the volume is offline. 


Ejected 


When a volume is ejected, vcbDrvNum is Cleared and vcbDRefNun is set to the positive 
drive number. If vcbDrvNum is zero and vcbDRefNum Is positive, you know that the 
volume is ejected. Ejection implies being offline. There is no such thing as “premature 
ejection”. 


Summary 
vcebDrvNum >0 (DrvNum) 0 0 
vcbDRefNum <0 (DRefNum) <0 (-DrvNum) >0 (DrvNum) 


Please refrain from assuming anything about a VCB queue element beyond what is 
documented in Inside Macintosh, and don't expect it to always be 178 bytes in size. It 
grew when we went from MFS to HFS, and it may grow again. It’s safest to use calls 
like PBHGet VInfo to get the information that you need. 
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#107: Nulls in Filenames 
See also: The File Manager 


Written by: Rick Blair March 2, 1987 


Some applications (loosely speaking so as to include Desk Accessories, INITs, and 
what-have-you) generate or rename special files on the fly so that they are not explicitly 
named by the user via SFPutFile. Since the Macintosh file system is very liberal about 
filenames and only excludes colons from the list of acceptable characters, this can lead 
to some difficulties, both for the end user and for writers of other programs which may 
see these files. 


Other programs which might be backing up your disk or something similar may get 
confused. A program written in C will think it has found the end of a string when it hits a 
null (ASCII code 0) character, so nulls in filenames are especially risky. 


As a rule, filenames should only include characters which the user can see and edit. 
The only reasonable exception might be invisible files, but it can be argued that they 
are of dubious value anyway. You can argue “but what about my help file, | don’t want 
it renamed” but we already have what we think is the best approach for that situation. If 
you can’t find a configuration or other file because the user has renamed or moved it, 
then call SFGetFile and let the user find it. If the user cancels, and you can’t run 
without the file, then quit with an appropriate message. 


Please consider carefully before you put non-displaying characters in filenames! 
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#108: _AddDrive, Drvrinstall and _DrvrRemove 
See also: SCSI Developer’s Kit (available from APDA) 
Written by: Jim Friedlander March 2, 1987 


hs 


AddDrive, DrvriInstall and DrvrRemove were used in the sample 
SCSI Driver in the SCSI Development Package v 1.0. This technical note 
documents the parameters for these calls. 


_AddDrive 
_AddDrive adds a drive to the drive queue: 


FUNCTION AddDrive (DOE:DrvQE1, driveNum, refNum: INTEGER) :OSErr; 


AO (input) > pointer to DQE 
DO high word(input) - drive number 
DO low word(input) —> driver RefNum 
DO (output) — error code 


noErr (always returned) 


_Drvrinstall 

_DrvrInsta1l is used to install a driver. A DCE for the driver is created and its handle 
entered into the specified Unit Table position (-1 through —32). If the unit number is —4 
through —9, the corresponding ROM-based driver will be replaced: 


FUNCTION Drvrinstall(refNum: INTEGER): OSErr; 


DO (input) -> driver RefNum (—1 through —32 currently) 
DO (output) < error code 
noErr 
badUnitErr 
Technical Note #108 page 1 of2 _AddDrive, 


_Drvrinstall and_DrvrRemove 


_DrvrRemove 


_DrvrRemove is used to remove a driver. A RAM-based driver is purged from the 
system heap (using ReleaseResource). Memory for the DCE is disposed: 


FUNCTION DrvrRemove (refNum: INTEGER) :OSErr; 


DO (input) > Driver RefNum 
DO (output) — error code 
noErr 
qErr 
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_Drvrinstall and_DrvrRemove 
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#109: Bug in MPW 1.0 Language Libraries 
See also: MPW Reference Manual 


Written by: Scott Knaster March 2, 1987 


This note describes a problem in the language libraries for MPW 1.0 If you 
use MPW Pascal or MPW C, the information in this note pertains to you. 


———a— $$ 


When you use the MPW Pascal or C compilers, the MPW Linker adds several runtime 
support routines to your object code. These routines are added automatically, and all 
applications whose main program is written in MPW Pascal or C have these routines in 
their object code. 


One routine, called RTEXIT, has a bug which destroys two important 68000 interrupt 
vectors (specifically, it places a longword-sized zero at RAM location $E, destroying the 
address error and illegal instruction vectors). This routine is executed as the 
application is terminating and returning to the Finder. 


To the application’s user, this problem has virtually no effect: it means that if 
subsequent programs would “normally” crash with an illegal instruction error or address 
error (both are system errors), they will instead crash with a different system error. 


For a programmer attempting to debug subsequent applications, this problem can be 
much more annoying. It means that illegal instruction errors and address errors will not 
be trapped by a debugger, making debugging very difficult. 


This bug is fixed in MPW 1.0.2, available from APDA. For now, there is a workaround: 
when you're ready to exit your application, call ExitToShe1l. This will immediately 
end the application before RTEXIT can destroy the vectors. ExitToShell bypasses 
automatic closing of files opened by language 1/0 libraries (e.g. C’s fopen or Pascal's 
Reset), so you'll have to make sure to close them yourself. Note that even if you're 
careful in calling Exit ToShe11, another application created with MPW may destroy the 
interrupt vectors. If this happens, the only way to restore the interrupt vectors is to 
restart the system. 


Also, note that recent versions of the TMON debugger’s user area save and restore the 
interrupt vectors around invocations of TMON, so you may not be able to observe this 
problem if you’re using TMON. 
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#110: MPW: Writing Standalone Code in MPW Pascal 


See also: Window Manager 
MPW Reference Manual 
Technical Note #14—The INIT 31 Mechanism 


Written by: Jim Friedlander March 2, 1987 


MPW Pascal can be used to write standalone code such as WDEFs, LDEFs, 
INITs and FKEYs. This technical note, which is not intended to be a 
complete discussion of the issues involved in writing standalone code, 
shows how to produce such standalone code using the Pascal compiler and 
the Linker, including an example of an INIT and a shell for making a WDEF. 


Limitations to standalone code 


«Standalone code cannot use globals. 
«Standalone code cannot directly access other globals (such as QuickDraw’s). 
«Standalone code cannot be segmented, or call code that is in other segments. 


Writing an INIT 


An INIT is merely standalone code that is executed on startup in the manner specified 
in Technical Note #14. INITs are commonly written is assembly language, but can also 
be written in high-level languages such as Pascal. Here’s the source for a simple, but 
nonetheless highly obnoxious, INIT written in MPW Pascal: 


UNIT MyInit; {standalone code is written as a UNIT) 
INTERFACE 
USES 
{$Load PasDump.dump} 
Memt ypes, QuickDraw, OSIntf,Toolintf; 
{NOTE: We cannot use global variables, since we are writing standalone code} 


PROCEDURE BeepTwice; 


IMP LEMENTATION 
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PROCEDURE BeepTwice; 
VAR finalTicks: LongInt; 


Begin {BeepTwice} 
SysBeep (1) ; 
Delay (120,finalTicks); {Delay two seconds, this'll annoy ‘em!} 
SysBeep (1) ; 

End; {BeepTwice} 


End. {UNIT} 


That’s all there is to the Pascal! Now we need to link the code to produce a standalone 
module. Here are the instructions that we use: 


pascal Init.p 


Compile the unit to output file Init .p.o 


link -rt INIT=0 @ 
-m BEEPTWICE ð 
-ọ MyInit @ #output to this file 
Init.p.o ð #link this object file first!!! then . 
“{Libraries}"interface.o 


Link to resource type INIT, ID 0 (-rt...). The main entry point is specified by the -m 
option. Pascal Units do not have a main entry point, and, since we are linking with 
"{Libraries}"interface.o (we need the glue for Delay), we need to tell the 
Linker what to strip against. We could link this without the -m option, but then all 
the code for "{Libraries}"interface.o would wind up in our INIT, making the 
INIT much larger than it needs to be. Notice also that we need to capitalize 
BEEPTWICE, since Pascal converts all module names to uppercase. 


Next we specify the files we wish to link with. Since the Linker links files in the 
order they are specified, we need to list Init.p.o first, otherwise the first 
instruction for our code will not be BeepTwice, but rather the glue for Delay 
(which is disastrous!). INITs are entered at the beginning, regardless of where the 
main entry point is. | 


lf you have any doubts about what the entry point is (and you can read assembler) 
you can use the command DumpCode MyInit -rt INIT to look at the code. In 
this case, the first code that is executed should be: 


LINK A6, #S5FFFC zsmake room for the local var ‘ilong' 


lf we had incorrectly specified "{Libraries}"interface.o first, the first code 
that would have been executed would have been the glue for Delay (and the 
code for our INIT would never have been executed): 


Execute ourselves 

address of VAR parameter 
finish getting ready for Delay 
do the Delay 


MOVE.L (A7)+,D0 
MOVE.L (A7)+,Al 


ws we we 7] 


_Delay 
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MOVE.L DO, (Al) ; the VAR parameter 

RTS ; return — but to where??? 

LINK A6, #SFFFC ; the correct code, but it’ll never 
: ; be executed 


SetFile MyInit -t INIT -c JAF1 && ð 
duplicate -y MyInit "{SystemFolder}" 


This command sets the file type of MyInit to INIT (so that the INIT 31 mechanism 
will run it) and the creator to JAF1. (Yes, JAFi Is registered with Macintosh 
Technical Support, is your file type?) If the Setrile succeeds, we then 
courageously duplicate the INIT into the system folder, so it will be executed the 
next time the system is rebooted. 


That’s all there is to it!! 


Now for a couple of caveats. As mentioned above, you cannot safely use globals in 
Standalone code. If we had put the line VAR gLong: Longint; fight after the 
keyword INTERFACE, the code would have compiled and linked OK, and probably 
executed OK. You will get no warning that you have used someone else’s 
global space! If we had used the statement gLong:= 4; the long word value 4 
would have been placed at -4 (A5) , thus destroying whatever was there (generally, the 
first of the application's globals). This is not really a problem with INITs (it definitely is a 
problem in the WDEF example below), but, in general, you should not use globals in 
standalone code. If something isn’t working correctly, you might look for inadvertent 
use of globals. 


Another limitation of standalone code is that it can’t use other globals such as 
QuickDraw globals. For example, if we had tried to use the statement 
SetPort (thePort) ; (which uses the QuickDraw global variable thePort) we would 
have been informed about our transgression: 


### link: Error Undefined entry, name: QUICKDRAW 
Referenced from: BEEPTWICE in file: Init.p.o 


You can access QuickDraw globals from standalone code, by using A5 (available from 
high-level languages in the low-memory global CurrentA5 (a long word at $904) 
which is a pointer to a pointer to thePort (@thePort = (A5)). Some of the standard 
Pascal library routines require the use of globals, you will get similar Linker errors if you 
use these routines. 


Writing a WDEF 


Writing a WDEF is basically the same as writing an INIT, except that WDEFs have 
(optional) standard headers that need to be incorporated into the code. In this 
example, our WDEF will be the Pascal FUNCTION MyWindowDef. To create the 
header, we need to use a small assembly language stub: 
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StdWDEF MAIN EXPORT ; this will be the main entry point 


IMPORT MyWindowDef ; name of the Pascal function that is the WDEF. 
7 we only need to IMPORT the externally referenced 
* routines from the Pascal (in this case, just 
; this one) 


WDEFHeader ; the main entry point of our WDEF 
BRA.S Q0 ; branch around the header to the actual code 
DC.W 0 ; flags word 
DC.B 'WDEF ! ;: type 
DC.W 3 ; ID 
DC.W 0 version 
@0 dummy label, header branches to here 


JMP MyWindowDef need this so Linker won't strip out MyWindowDef. 


this also jumps to the entry point of the WDEF. 


se y ws ë Ws 


END 


Now for the Pascal source for the WDEF. Only the shell of what needs to be done will 
be listed, the actual code will be left as an exercise for the reader (for further 
information about writing a WDEF, see Inside Macintosh, pages 1-297 through l-302): 


UNIT WDef; 
INTERFACE 
USES 
{$Load PasDump.dump} 
Memt ypes, QuickDraw,OSIntf,Toolintf; 
{NOTE: We can’t use globals here} 
FUNCTION MyWindowDef {this is the only external routine} 


(varCode: Integer; theWindow: WindowPtr; message: Integer;param: LongInt): 
Longint; {As defined in IM p. 1-299} 


IMPLEMENTATION 
FUNCTION MyWindowDef (varCode: Integer; theWindow: WindowPtr; 


message: Integer; param: LongInt): LongInt; 


TYPE 
RectPtr = “Rect; 


VAR 
aRectPtr :RectPtr; {notice that this is local, not global!} 
{here are the routines that are dispatched to by MyWindowDef} 
PROCEDURE DoDraw(theWind: WindowPtr; DrawParam: LongInt); 
{we can have local variables here, if we wish} 


BEGIN {DoDraw} 
{Fill in the code! } 
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END; {DoDraw} 


FUNCTION DoHit (theWind: WindowPtr; theParam: LongInt): LongInt; 


BEGIN {DoHit } 
{Code for this FUNCTION goes here} 
END; {DoHit } 


PROCEDURE DoCalcRgns (theWind: WindowPtr) ; 


BEGIN {DoCalcRgns} 
{Code for this PROCEDURE goes here} 
END; {DoCalcRgns} 


PROCEDURE DoGrow(theWind: WindowPtr; theGrowRect: Rect); 


BEGIN {DoGrow} 
{Code for this PROCEDURE goes here} 
END; {DoGrow} 


PROCEDURE DoDrawSize (theWind: WindowPtr); 


BEGIN {DoDrawSize} 
{Code for this PROCEDURE goes here} 
END; {DoDrawSize} 


{now for the main body to MyWindowDef} 

BEGIN { MyWindowDef } 

{case out on the message and jump to the appropriate routine} 
MyWindowDef := 0; {initialize the function result} 
CASE message OF 

wDraw: { draw window frame} 
DoDraw (theWindow, param) ; 

wHit: { tell what rgn the mouse was pressed in} 
MyWindowDef := DoHit (theWindow, param) ; 

wCalcRgns: { calculate structRgn and contRgn} 
DoCalcRgns (theWindow) ; 

wNew: { do any additional initialization} 
{ we don’t need to do any} 

wDispose:{ do any additional disposal actions} 
{ we don’t need to do any} 

wGrow: { draw window’s grow image] 
BEGIN 

aRectPtr := RectPtr (param); 
DoGrow (theWindow, aRectPtr“%) ; 

END; {CASE wGrow} 

wDrawGlIcon:{ draw Size box in content rgn} 
DoDrawSize (theWindow) ; 

END; {CASE} 
END; {MyWindowDef } 
END. {of UNIT} 
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Here are the MPW shell commands necessary to build this WDEF: 


pascal MyWDEF.p 
asm MyWDEF.a 
link -rt WDEF=3 ĝ 
-t '2222' ð 
-c 'JAF1' @ 
-o MyWDEF3 a 
MyWDEF.a.o ð # MUST link with this first 
MyWDEF.p.o @ 
"{Libraries}"interface.o 


Notice that we don’t need the -m option, since MyWDEF .a.o contains the main 
entry point, so the Linker knows what to strip against. 


That’s all there is to it! 


Writing a WDEF with no header 


If you want to have a WDEF without the recommended header, you have to make 
changes to the Pascal code and use a different link command. Here's the link 
statement: 


pascal MyWDEF.p 
asm MyWDEF.a 
link -rt WDEF=3 ð 
-t '22272?' @ 
-m MYWINDOWDEF 
-c 'JAF1' @ 
-0 MyWDEF3 ð 
MyWDEF.p.o ð # link with this first 
"{Libraries}"interface.o #and then with this 


Notice here that we do need the -m option, since we aren't linking with the 
assembly header, and Pascal Units don’t have a main entry point. 


Since the MPW Pascal compiler generates code in the order that it reads the source, 
we need to unnest the DoDraw, DoHit, DoCaicRgns, DoGrow and DoDrawSize 
routines and place them after MyWindowDef, so that the code for MyWindowDef is first. 
To do this, we also need to declare them as FORWARD in the IMPLEMENTATION section 
of the Unit (so they can be referenced by MyWindowDef). If we left the above five 
routines nested, the entry point to the WDEF would be the code for DoDraw, not the 
code for MyWindowDef that dispatches to the various routines. Of course, this is a 
serious problem. If you think that this is happening, you can examine the output of the 
Pascal compiler with the DumpOb j tool. 
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#111: MoveHHi and SetResPurge 


See also: Memory Manager 
Resource Manager 


Written by: Jim Friedlander March 2, 1987 





SetResPurge (TRUE) is called to make sure that the Memory Manager will call the 
Resource Manager before purging a block specified by a handle. If the handle is a 
handle to a resource, and its resChanged bit is set, the resource data will be written out 
(using WriteResource). 


This is also true of a handle that is being moved to the top of the heap with MoveHHi. 
Even though the handle’s block is not actually being purged, the resource data 
specified by the handle will be written out. An application can prevent this by calling 
SetResPurge (FALSE) before calling MoveHHi (and then calling SetResPurge (TRUE) 
after the MoveHHi Call). 
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#112: FindDitem 
See also: Dialog Manager (Volume IV) 


Written by: Rick Blair March 2, 1987 


FindDitem is a potentially useful call which returns the number of a dialog item given a 
point in local coordinates and a dialog handle. It returns an item number of —1 if no 
item’s rectangle overlaps the point. This is all well and good, except you don’t get back 
quite what you would expect. 


The item number returned is zero-based, so you have to add one to the result: 


theitem := FindDItem(theDialog, thePoint) + 1; 
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#113: Boot Blocks 
See also: The Segment Loader 


Written by: Bo3b Johnson March 2, 1987 





-m 


There are two undocumented features of the Boot Blocks. This note will 
describe how they currently work. 


Warning: The format and functionality of the Boot Blocks will change in the 
future; dependence on this information may cause your program to fail on 
future hardware or with future System software. 





The first two sectors of a bootable Macintosh disk are used to store information on how 
to start up the computer. The blocks contain various parameters that the system uses to 
startup such as the name of the system file, the name of the Finder, the first application 
to run at boot time, the number of events to allow, etc. 


Changing System Heap Size 


The boot blocks dictate what size the system heap will be after booting. Any common 
sector editing program will allow you to change the data in the boot blocks. Changing 
the system heap size is accomplished by changing two parameters in the boot blocks: 
the long word value at location $86 in Block 0 indicates the size of the system heap; 
the word value at location $6 is the version number of the boot blocks. Changing the 
version number to be greater than $14 ($15 is recommended) tells the ROM to use the 
value at $86 for the system heap size, otherwise the value at $86 is ignored. The $86 
location only applies to computers with more than 128K of RAM. 


Secondary Sound and Video Pages 


Another occasionally useful feature of the boot blocks is the ability to specify that the 
secondary sound and video pages be allocated at boot time. This is done before a 
debugger is loaded, so the debugger will load below the alternate screen. This is 
useful for debugging software that uses the alternate video page, like page-flipping 
demos or games. To allocate the second video and sound buffers, change the two 
bytes starting at location $8 in the boot blocks. Change the value (normally 0) to a 
negative number ($FFFF) to allocate both video and sound buffers. Change the value 
to a positive number ($0001) to allocate only the secondary sound buffer. 
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Warning: MacsBug may not work properly if you allocate additional pages for sound 
and video. 
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#114: AppleShare and Old Finders 
See also: AppleShare User's Guide 
Written by: Bryan Stearns March 2, 1987 


A rumor has been spread that if you use a pre-AppleShare Finder on a workstation to 
access AppleShare volumes, you can bypass AppleShare’s “access privilege” 
mechanisms. 


This is not true. All access controls are enforced by the server, not by the Finder. If you 
use an older Finder, you are still prevented (by code running on the server) from gaining 
access to protected files and folders; however, you will not get the proper user-interface 
feedback that you would if you were using the correct Finder: for instance, folders on the 
server would always appear plain white (that is, without the permission feedback you'd 
normally get), and error messages would not be as explanatory as those that “know” 
about AppleShare servers. 
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#115: Application Configuration with Stationery Pads 


See also: The File Manager 
Technical Note #116: AppleShare-able Applications 
Technical Note #47: Customizing SFGetFile 
Technical Note #48: Bundles 
“Application Development in a Shared Environment” 


Written by: Bryan Stearns March 2, 1987 


With the introduction of AppleShare (Apple's file server) there are 
restrictions on self-modification of application resource files and the 
placement of configuration files. This note describes one way to get around 
the necessity for configuration files. 


Configuration Files 


some applications need to store information about configuration; others could benefit 
simply from allowing users to customize default ruler settings, window placement, fonts, 
etc. 


There are applications which store this information as additional resources in the 
application’s resource file; when the user changes the configuration, the application 
writes to itself to change the saved information. 


AppleShare, however, requires that if an application is to be used by more than one 
user at a time, it must not need write access to itself. This means that the above method 
of storing configuration information cannot be used. (For more information about 
making your application sharable, see Technical Note #116.) 


Storing configuration in a special configuration file can be a problem; the user must 
keep the file in the system folder or the application must search for it. This process has 
design issues of its own. 

An alternative to configuration files: Stationery Pads 

A basis for one solution to this problem was a user-interface feature of the Lisa Office 
System architecture. Lisa introduced the concept of “stationery pads”, special 


documents that created copies of themselves to allow users to save a pre-set-up 
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document for future use. On Lisa, this was the way Untitled documents were created. 
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Your Macintosh application can provide the option of saving a document as a 
Stationery pad, to provide similar functionality. Here’s how: 


¢ You'll need to add a checkbox to your SFPutFile dialog box (if you don’t know 
how to do this, check out Technical Note #47); if the user checks this box, save 
the document as you normally would, but use a different file type (the file type of a 
document is usually set when the document is created, using the File Manager 
Create procedure, or later using SetFileInfo). 





e Be sure to use a different but similar icon for the stationery pad file. This is easy if 
you differentiate between stationery and normal files solely by file type—the 
Finder uses the type to determine which icon to display, see Technical Note #48 
for help with the “bundle” mechanism used to associate a file type with an icon. 


e When opening a stationery pad file, the window should come up named 
“Untitled”, with the contents of the stationery pad file. 


e “Revert” should re-read the stationery pad file. 
e Don't forget to add the stationery pad’s file type to the file-types list that you pass 
to Standard File, so that the new files will appear in the list when the user 


chooses Open. This file type should be registered with Macintosh Developer 
Technical Support. 
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#116: AppleShare-able Applications and the Resource Manager 


See also: The Resource Manager 
“Application Development in a Shared Environment” (from 
APDA) 
Technical Note #40—Finder Flags 


Written by: Bryan Stearns March 2, 1987 


Normally, applications on an AppleShare server volume cannot be executed 
by more than one user at a time. This technical note explains why, and tells 
how you can enable your application to be shared. 


The Resource Manager versus Shared Files 


Part of the explanation of why applications are not automatically sharable is based on 
the design of the Resource Manager. The Resource Manager is a great little database. It 
was originally conceived as a way to keep applications localizable (a task it has 
performed admirably), and was found to be an excellent foundation for the Segment 
Loader, Font Manager, and a large part of the rest of the Macintosh operating system. 


However, it was never designed to be a multi-user database. When the Resource 
Manager opens a resource file (such as an application), it reads the file’s resource map 
into memory. This map remains in memory until the resource file is closed by the 
Segment Loader, which regains control when the application exits. Sometimes it is 
necessary to write the map out to disk; normally, this is only done by UpdateResFile 
and CloseResFile. 


If two users opened the same resource file at the same time, and one of them had write 
access to the file and added a resource to it, the other user's Resource Manager 
wouldn't know about it; this would make the other user’s copy of the file’s original 
resource map invalid. This could cause (at least) a crash; if both users had write access, 
it's not unlikely that the resource file involved would become corrupted. Also, although 
you can tell the Resource Manager to write out an updated resource map, there's no way 
for another user to tell it to refresh the copy of the map in memory if the file changes. 
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What does all this have to do with running my application twice? 


Your application is stored as a resource file; code segments, alert and dialog templates, 
etc., are resources. If you write to your application’s resource file (for instance, to add 
configuration information, like print records), your application can’t be shared. 


In Apple’s compatibility testing of existing applications (during development of 
AppleShare), we found quite a few applications, some of them quite popular, that wrote 
to their own resource files. So we decided, to improve the safety of using AppleShare, to 
always launch applications using a combination of access privileges such that only one 
user at a time could use a given application (these privileges will be discussed in a 
future Technical Note). In fact, AppleShare opens all resource files this way, unless the 
resource file is opened with OpenRFPerm and read-only permission is specified. 


But my application doesn’t write to itself! 


We realize that many applications do not. However, there are other considerations 
(covered in detail, with suggestions for fixes, in “Application Development in a Shared 
Environment’, available from APDA ). In brief, here are the big ones we know about: 


e Does your application create temporary files with fixed names in a fixed place (such 
as the directory containing the application)? Without AppleShare’s protection, two 
applications trying to use the same temporary file could be disastrous. 


e Is your application at feast “conscious” of the fact that it may be in a multi-user 
environment? For instance, does it work correctly if a volume containing an existing 
document is on a locked volume? Does it check all result codes returned from File 
Manager calls, and ResError after relevant Resource Manager calls? 


OK, | follow the rules. What do | do to make my application 
sharable? 


There is a flag in each file’s Finder information (stored in the file’s directory entry) known 
as the “shared” bit. If you set this bit on your application's resource file, the Finder will 
launch your application using read-only permissions; if anyone else launches your 
application, they'll also get it read-only (their Finder will see the same “shared” bit set.). 


Three important warnings accompany this information: 


¢ The definition of the “shared” bit was incorrect in previous releases of information and 
software from Apple. This includes the June 16, 1986 version of Technical Note #40 
(fixed in the March 2, 1987 version), as well as all versions of ResEdit before and 
including 1.0 (released with MPW 1.0). For now, the most reliable way to set this bit is 
to get the 1.0 version of ResEdit, use it to Get Info on your application, and check the 
box labeled “cached” (the incorrect documentation upon which ResEdit [et al.] was 
based called the real shared bit “cached”; the bit labeled as “shared” is the real 
cached bit [a currently unused but reserved bit which should be left clear]). 
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e By checking this bit, you’re promising (to your users) that your application will work 
entirely correctly if launched by more than one user. This means that you follow the 
other rules, in addition to simply not writing to your application’s own resource file. 
see “Application Development for a Shared Environment,” and test carefully! 


e Setting this bit has nothing to do with allowing your application’s documents to be 
shared; you must design this feature into your application (it’s not something that 
Apple system software can take care of behind your application’s back.). You should 
realize from reading this note, however, that if you store your document’s data in 
resource files, you won’t be able to allow multiple users to access them 
simultaneously. 
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#117: Compatibility: Why & How (Part l) 


See Also: Technical Note #2—Macintosh Compatibility Guidelines 
Technical Note #7—A Few Quick Debugging Tips 


Written by: Bo3b Johnson February 9, 1987 


While creating or revising any program for the Macintosh, you should be 
aware of the most common reasons why programs fail on various versions 
of the Macintosh. This technical note will detail some common failure 
modes, why they occur, and how to avoid them. 


We've tried to explain the issues in depth, but recognize that not everyone is interested 
in every issue. For example, if your application is not copy protected, you’re probably 
not very interested in the section on copy protection. That's why we've included the 
outline form of the technical note. The first two pages outline the problems and the 
solutions that are detailed later. Feel free to skip around at will, but remember that 
we're sending this enormous technical note because the suggestions it provides may 
save you hasty compatibility revisions when we announce a new machine. 


We know it’s a lot, and we’re here to help you if you need it. Our address (electronic 


and physical) is on page three—contact us with any questions—that’s what we're here 
for! 
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Compatibility: the outline 


Don’t assume the screen is a fixed size 
To get the screen size: 
e check the QuickDraw global screenBits.bounds 


Don’t assume the screen is in a fixed location 
To get the screen location: 
e check the QuickDraw global screenBits.baseAddr 


Don’t assume that rowBytes is equal to the width of the screen 
To get the number of bytes on a line: 
e check the QuickDraw global screenBits.rowBytes 
To get the screen width: 
e check the QuickDraw global screenBits.bounds.right 
To do screen-size calculations: 
e Use LongInts 


Don’t write to or read from nil Handles or nil Pointers 


Don’t create or Use Fake Handles 

To avoid creating or using fake handles: 
* Always let the Memory Manager perform operations with handles 
« Never write code that assigns something to a master pointer 


Don’t write code that modifies itself 
Self modifying code will not live across incarnations of the 68000 


Think carefully about code designed strictly as copy protection 
To avoid copy protection-related incompatibilities: 

e Avoid copy protection altogether 

e Rely on schemes that don’t require specific hardware 

e Make sure your scheme doesn't perform illegal operations 


Don’t ignore errors 

To get valuable information: 
¢ Check all pertinent calls for errors 
e Always write defensive code 


Don’t access hardware directly 

To avoid hardware-related incompatibilities: 
¢ Don’t read or write the hardware 
¢ If you can’t get the support from the ROM, ask the system where the hardware is 
¢ Use low-memory globals 


Don’t use bits that are reserved 
To avoid compatibility problems when bit status changes: 
¢ Don’t use undocumented stuff 
¢ When using low-memory globals, check only what you want to know 
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summary | 
Minor bugs are getting harder and harder to get away with: 
¢ Good luck 
e We'll help 
¢ MCI: MACTECH 
* US Mail: 20525 Mariani Ave. MS 27-T; Cupertino, CA 95014 
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What it Is 


The basic idea is to make sure that your programs will run, regardless of which 
Macintosh they are being runon. The current systems to be concerned with include: 


e Macintosh 128K 
* Macintosh 512K 
e Macintosh XL 

e Macintosh 512Ke 
e Macintosh Plus 

e Macintosh SE 

+ Macintosh II 


if you perform operations in a generic fashion, there is rarely any reason to know what 
machine is running. This means that you should avoid writing code to determine which 
version of the machine you are running on, unless it is absolutely necessary. 


For the purposes of this discussion, the term “programs” will be used to describe any 
code that runs on a Macintosh. This includes applications, INITs, FKEYs, Desk 
Accessories and Drivers. 


What the “Rules” mean 


Compatibility across all Macintosh computers (which may sound like it involves more 
work for you) may actually mean that you have less work to do, since it may not be 
necessary to revise your program each time Apple brings out a new computer or 
System file. Users, as a group, do not understand compatibility problems; all they see 
is that the program does not run on their system. 


The benefits of being compatible are many-fold: your customers/users stay happy, you 
have less programming to do, you can devote your time to more valuable goals, there 
are fewer versions to deal with, your code will probably be more efficient, your users 
will not curse you under their breath, and your outlook on life will be much merrier. 


Now that we know what being compatible is all about, recognize that nobody is 
requiring you to be compatible with anything. Apple does not employ roving gangs of 
thought police to be sure that developers are following the recommended guidelines. 
Furthermore, when the guidelines comprise 1200 pages of turgid prose (/nside 
Macintosh), you can be expected to miss one or two of the “rules”. It is no sin to be 
incompatible, nor is it a punishable offense. If it were, there would be no Macintosh 
programs, since virtually all developers would be incarcerated. What it does mean, 
however, is that your program will be unfavorably viewed until it steps in line with the 
current system (which is a moving target). If a program becomes incompatible with a 
new Macintosh, it usually requires rethinking the offending code, and releasing a new 
version. You may read something like “If the developers followed Apple guidelines, 
they would be compatible with the transverse-hinged diatomic quark realignment 
system.” This means that if you made any mistakes (you read all 1200 pages carefully, 
right?), you will not be compatible. It is extremely difficult to remain completely 
compatible, particularly in a system as complex as the Macintosh. The rules haven't 
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changed, but what you can get away with has. There are, however, a number of things 
that you can do to improve your odds—some of which will be explained here. 


It’s your choice 


It is still your choice whether you will be concerned with compatibility or not. Apple will 
not put out a warrant for your arrest. However, if you are doing things that are 
specifically illegal, Apple will also not worry about “breaking” your program. 


Bad Things 


The following list is not intended to be comprehensive, but these are the primary 
reasons why programs break from one version of the system to the next. These are the 
current top ten commandments: 


| Thou shalt not assume the screen is a fixed size. 

lI Thou shalt not assume the screen is at a fixed location. 

lll Thou shalt not assume that rowBytes is equal to the width of the screen. 

IV Thou shalt not use nil handles or nil pointers. 

V Thou shalt not create or use fake handles. 

VI Thou shalt not write code that modifies itself. 

VII Thou shalt think twice about code designed strictly as copy protection. 

VIII Thou shalt check errors returned as function results. 

IX Thou shalt not access hardware directly. 

X Thou shalt not use any of the bits that are reserved (unused means reserved). 


This has been determined from extensive testing of our diverse software base. 
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Assuming the screen is a fixed size 


Do not assume that the Macintosh screen is 512 x 342 pixels. Programs that do 
generally have problems on (or special case for) the Macintosh XL, which has a wider 
screen. Most applications have to create the bounding rectangle where a window can 
be dragged. This is the boundsRect that is passed to the call: 


DragWindow (myWindowPtr, theEvent.where, boundsRect) ; 
some ill-advised programs create the boundsRect by something like: 


setRect (boundsRect, 0,0,342,512); { oops, this is hard-coded..} 
Why It’s Bad 


This is bad because it is never necessary to specifically put in the bounding rectangle 
for the screen. On a Macintosh XL for example, the screen size is 760x364 (and 
sometimes 608x431 with alternate hardware). if a program uses the hard-coded 
0,0,342,512 as a bounding rectangle, end users will not be able to move their windows 
past the fictitious boundary of 512. If something similar were done to the GrowWindow 
call, it would make it impossible for users to grow their window to fill the entire screen. 
(Always a saddening waste of valuable screen real-estate.) 


Assuming screen size makes it more difficult to use the program on Macintoshes with 
big screens, by making it difficult to grow or move windows, or by drawing in strange 
places where they should not be drawing (outside of windows). Consider the case of 
running on a Macintosh equipped with one of the new full page displays, or Ultra-Large 
screens. No one who paid for a big screen wants to be restricted to using only the 
upper-left corner of it. 


How to avoid becoming a screening fascist 


Never hard code the numbers 512 and 342 for screen dimensions. You should avoid 
using constants for system values that can change. Parameters like these are nearly 
always available in a dynamic fashion. Programs should read the appropriate 
variables while the program is running (at run-time, not at compile time). 


Here’s how smart programs get the screen dimensions: 


InitGraf (@thePort); { QuickDraw global variables have to be initialized.) 


boundsRect := screenBits.bounds; { The Real way to get screen size } 
{ Use QuickDraw global variable. } 


This is smart, because the program never has to know specifically what the numbers 
are. All references to rectangles that need to be related to the screen (like the drag and 
grow areas of windows) should use screenBits.bounds to avoid worrying about the 
screen size. Note that this does not do anything remotely like assume that “if the 
computer is not a standard Macintosh, then it must be an XL.” Special casing for the 
various versions of the Macintosh has always been suspicious at best; it is now 
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grounds for breaking. (At least with respect to screen dimensions.) 


By the way, remember to take into account the menu bar height when using this 
rectangle. On 128K ROMs (and later) you can use the low-memory global 
mBarHeight (a word at $BAA). But since we didn’t provide a low-memory global for the 
menu bar height in the 64K ROMs, you'll have to hard code it to 20 ($14). (You're not 
the only ones to forget the future holds changes.) 


How to find fascist screenism in current programs 


The easiest way is to exercise your program on one of the Ultra-Large screen 
Macintoshes. There should be no restrictions on sizing or moving the windows, and all 
drawing should have no problems. If there are any anomalies in the program's usage, 
there is probably a lurking problem. Also, do a global find in the source code to see if 
the numbers 512 or 342 occur in the program. If so, and if they are in reference to the 
screen, excise them. 
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Assuming the screen is at a fixed location 


Some programs use a fixed screen address, assuming that the screen location will be 
the same on various incarnations of the Macintosh. This is not the case. For example, 
the screen is located at memory location $1A700 on a 128K Macintosh, at $7A700 ona 
512K Macintosh, at $F 8000 on the Macintosh XL, and at $F A700 on the Macintosh 
Plus. 


Why it’s Bad 


When a program relies upon the screen being in a fixed location, Murphy’s Law 
dictates that an unknowing user will run it upon a computer with the screen in a 
different location. This usually causes the system to crash, since the offending program 
will write to memory that was used for something important. Programs that crash have 
been proven to be less useful! than those that don't. 


How to avoid being a base screener 


Suffice it to say that there is no way that the address of the screen will remain static, but 
there are rare occasions where it is necessary to go directly to the screen memory. On 
these occasions, there are bad ways and not-as-bad ways to do it. A bad way: 


myScreenBase := Pointer ($7A700); { not good. Hard-coded number. } 


A not-as-bad way: 
InitGraf (@thePort) ; { do this only once in a program. } 


myScreenBase := screenBits.baseAddr; { Good. Always works. } 
{Yet another QuickDraw global variable} 


Using the latter approach is guaranteed to work, since QuickDraw has to know where 
to draw, and the operating system tells QuickDraw where the screen can be found. 
When in doubt, ask QuickDraw. This will work on Macintosh computers from now until 
forever, so if you use this approach you won't have to revise your program just because 
the screen moved in memory. 


If you have a program (such as an INIT) that cannot rely upon QuickDraw being 
initialized (via InitGraf), then it is possible to use the ScrnBase low-memory global 
variable (a long word at $824). This method runs a distant second to asking 
QuickDraw, but is sometimes necessary. 


How to find base screeners 


The easiest way to find base screeners is to run the offending program on machines 
that have different screen addresses. If any addresses are being used in a base 
manner, the system will usually crash. The offending program may also occasionally 
refuse to draw. Some programs afflicted with this problem may also hang the computer 
(sometimes known as accessing funny space). Also, do a global find on the source 
code to look for numbers like $7A700 or $1A700. When found, exercise caution while 
altering the offending lines. 
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Assuming that rowbytes is equal to the width of the screen 


According to the definition of a bitMap found in Inside Macintosh (p |-144), you can see 
that rowBytes is the number of actua! bytes in memory that are used to determine the 
bitMap. We know the screen is just a big hunk of memory, and we know that 
QuickDraw uses that memory as a bitMap. rowBytes accomplishes the translation of 
a big hunk of memory into abitMap. To do this, rowBytes tells the system how long a 
given row is in memory and, more importantly, where in memory the next row starts. 
For conventional Macintoshes, rowBytes (bytes per Row) « 8 (Pixels per Byte) gives 
the final horizontal width of the screen as Pixels per Row. This does not have to be the 
case. It is possible to have a Macintosh screen where the rowBytes extends beyond 
what is actually visible on the screen. You can think of it as having the screen looking 
in on a larger bitMap. Diagrammatically, it might look like: 


Big Hunk o’ Memory 


RowBytes 


screenBits.Bounds 


BaseAGdr i} z er 2 4 et PO OA POHL? 





With an Ultra-Large screen, the number of bytes used for screen memory may be in the 
500,000 byte range. Whenever calculations are being made to find various locations in 
the screen, the variables used should be able to handle larger screen sizes. For 
example, a 16 bit Integer will not be able to hold the 500,000 number, so a LongInt 
would be required. Do not assume that the screen size is 21,888 bytes long. bitMaps 
can be larger than 32K or 64K. 


Why it’s Bad 


Programs that assume that all of the bytes in a row are visible may make bad 
calculations, causing drawing routines to produce unusual, and unreadable, results. 
Also, programs that use the rowBytes to figure out the width of the screen rectangle 
will find that their calculated rectangle is not the real screenBits.Bounds. Drawing 
into areas that are not visible will not necessarily crash the computer, but it will 
probably give erroneous results, and displays that don’t match the normal output of the 
program. Programs that assume that the number of bytes in the screen memory will be 
less than 32768 may have problems drawing into Ultra-Large screens, since those 
screens will often have more memory than a normal Macintosh screen. These 
particular problems do not evidence themselves by crashing the system. They 
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generally appear as loss of functionality (not being able to move a window to the 
bottom of the screen), or as drawing routines that no longer look correct. These 
problems can prevent an otherwise wonderful program from being used. 


How to avoid being a row byter 


in any calculations, the rowBytes variable should be thought of as the way to get to the 
next row on the screen. This is distinct from thinking of it as the width of the screen. 
The width should always be found from screenBits.bounds.right-— 
screenBits.bounds.ileft. 


It is also inappropriate to use the rectangle to decide how many bytes there are on a 
row. Programs that do something like: 


bytesLine := screenBits.bounds.right DIV 8; { bad use of bounds } 
rightSide := screenBits.rowBytes x 8; { bad use of rowBytes } 


will find that the screen may have more rowBytes than previously thought. The best 
way to avoid being a row byter is to use the proper variables for the proper things. 
Without the proper mathematical basis to the screen, life becomes much more difficult. 
Always do things like: 


bytesLine := screenBits.rowBytes; { always the correct number } 
rightSide := screenBits.bounds.right; { always the correct screen size } 


It is sometimes necessary to do calculations involving the screen. If so, be sure to use 
Longints for all the math, and be sure to use the right variables (i.e. use LongInts). 
For example, if we need to find the address of the 500th row in the screen (500 lines 
from the top): 


VAR myAddress: tLongint; 
myRow : Longint ; { so the calculations don’t round off. } 
myOffset: LongInt; { could easily be over 32768 ... } 
bytesLine: LongInt; 


myAddress := ord4(screenBits.baseAddr); (start w/the real base address } 
myRow := 500; {the row we want to address } 
bytesLine := screenBits.rowBytes; {the real bytes per line } 

myOffset := myRow * bytesLine; {lines * bytes per lines gives bytes 


myAddress := myAddress + myOffset; {final address of the 500th line } 
This is not something you want to do if you can possibly avoid it, but if you simply must 
go directly to the screen, be careful. The big-screen machines (Ultra-Large screens) 


will thank you for it. If QuickDraw cannot be initialized, there is also the low-memory 
global screenRow (a word at $106) that will give you the current rowBytes. 


How to find row byters 


To find current problems with row byter programs, run them on a machine equipped 
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with Ultra-Large screens and see if any anomalies crop up. Look for drawing 
sequences that don’t work right, and for drawing that clips to an imaginary edge. For 
source-levei inspection, look for uses of the rowBytes variables and be sure that they 
are being used in a mathematically sound fashion. Be highly suspicious of any code 
that uses rowBytes for the screen width. Any calculations involving those system 
variables should be closely inspected for round-off errors and improper use. Search 
for the number 8. If it is being used in a calculation where it is the number of bits per 
byte, then watch that code closely for improper conceptualization. This is code that 
could leap out and grab you by the throat at anytime. Be careful! 
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Using nil Handles or nil Pointers 


A nil pointer is a pointer that has a value of 0. Recognize that pointers are merely 
addresses in memory. This means that a nil pointer is pointing to memory location 0. 
Any use of memory location 0 is strictly forbidden, since it is owned by Motorola. 
Trespassers may be shot on sight, but they may not die until much later. Sometimes 
trespassers are only wounded and act strangely. Any use of memory location 0 can be 
considered a bug, since there are no valid reasons for Macintosh programs to read or 
write to that memory. However, nil pointers themselves are not necessarily bad. It is 
occasionally necessary to pass nil pointers to ROM routines. This should not be 
confused with reading or writing to memory location 0. A pointer normally points to 
{contains the address of) a location in memory. It could look like this: 


$3E4DE 


Highest Memory This is how a Pointer 

works. The address of 

the pointer variable itself 

is $E9310 (@P} and is four 
bytes long. The pointer points 
to {contains the address of) 
the block at $3E4DE (P). 

That memory location is where 
the actual data resides (P^), 











P: $E9310: 


Higher Memory 


P^: $3E4DE:) 


Memory 0 


lf a pointer has been cleared to nil, it will point to memory location 0. This is OK as 
long as the program does not try to read from or write to that pointer. An example of a 
nil pointer could look like: 


Highest Memor 
3 x This is a nil Pointer. 


Note that the memory that 
it points to (the address) 
is O (P*). This is wrong. 
There is no valid data at 
memory location 0. Any 
writing to or reading from 
this pointer is a bug. 


P: $E9310; 


Memory 0 
(P*) 
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nil handles are related to the problem, since a handle is merely the address of a 
pointer (or a pointer to a pointer). An example of what a normal handle might look like 


is: 


Highest Memory 





$2603C 


H: $E9310: 





This is how a Handle works. 
The address of the handle 
variable itself {H) is $E9310., 


That variable points (has the 
address) to the master pointer 

at location $2603C (H). That 
variable is a pointer also, and 
points to the real data found 

at S$3E4DE {H**}. The dark grey 
block is a Master pointer block. It 
is a group {usually 64) of Master 
Pointers. One of them is the Master 
Pointer at address $2603C (H^). 


Higher Memory 


H**: S3E4DE:F: 


Sa ee ee ey 
ae ae, See eas pin” a eae a, gp pana ge” nate iw 
ERRELE ERRE we ee ee a ee 


H^: $2603C: 












Memory 0 


When the first pointer (h) becomes nil, that implies that memory location 0 can be 
used as a pointer. This is strictly illegal. There are no cases where it is valid to read 
from or write to a nil handle. A pictorial representation of what a nil handle could 
look like: 


Highest Memory This is a nil Handle. 


Note that the Handle usually 

points to a Master Pointer, but 

in this case it points at (has 

the value of) O (H^). This is wrong. 
Using what is at memory location 

0 as a pointer is invalid, since 


Higher Memory 
it is not known what will be there. 


S3E4DE:/ 


H**: Points someplace strange... 


$2603C:] | 


Memory 0 
(H^) 


if the memory at 0 contains an odd number (numerically odd), then using it as a pointer 
will cause a system error with ID=2. This can be very useful, since that tells you exactly 
where the program is using this illegal handle, making it easy to fix. Unfortunately, 
there are cases where it is appropriate to pass a nil handle to ROM routines (such as 
GetScrap). These cases are rare, and it is never legal to read from or write to a nil 
handle. 


There is also the case of an empty handle. An empty handle is one where the handle 


Technical Note #117 page13 of 28 Compatibility: Why & How 


— 


itself (the first pointer) points to a valid place in memory; that place in memory is also a 
pointer, and if it is ni1 the entire handle is termed empty. There are occasions where it 
is necessary to use the handle itself, but using the ni1 pointer that it contains is not 
valid. An example of an empty handle could be: 


$2603C 


This is an Empty Handle. 

Note that the handle itself 

has a valid Master Pointer 
address in it $2603C (H^). The 
Master Pointer is nil however, 
which is the address of location 
0 in memory. It is wrong to use 
the Master Pointer in this case, 
although there are cases where 
using the Handle itself is valid. 


Highest Memory 









H: $E9310: 





Higher Memory 


S3E4DE:F =: 


M al ue" dwn T stetetitel 8,7 888 28s 
r EE a” ea ahaa” Ta Tat aTe Te ahaa Niel E 8 Sy 
Taha et as site tet ae nt aaa anda A dete a m een ae 


H^: $2603C: 


Bed Pa 
arnan arana anaana aa aeaea ana N a AR 


Memory 0 
(HS 


Fundamentally, any reading or writing to memory using a pointer or handle that is nil 
is punishable by death (of your program). 


Why it’s Bad 


The use of nil pointers can lead to the use of make-believe data. This make-believe 
data often changes for different versions of the computer. This changing data makes it 
difficult to predict what will happen when a program uses nil pointers. Programs may 
not crash as a result of using a nil pointer, and they may behave in a consistent 
fashion. This does not mean that there isn’t a bug. This merely means that the 
program is lucky, and that it should be playing the lottery, not running on a Macintosh. 
if a program acts differently on different versions of the Macintosh, you should think 
“could there be a nasty nil pointer problem here?” Use of a nil handle usually 
culminates in reading or writing to obscure places in memory. As an example: 


VAR myHandle: MTEHandle; 

myHandle := nil; 
That's pretty straightforward, so what's the problem? If you do something like: 

myHandle**.viewRect := myRect; { very bad idea with myHandle = nil } 
memory location zero will be used as a pointer to give the address of a TextEdit record. 
What if that memory location points to something in the system heap? What if it points 


to the sound buffer? In cases like these, eight bytes of rectangle data will be written to 
wherever memory location 0 points. 
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Use of a nil handle will never be useful. This memory is reserved and used by the 
68000 for various interrupt vectors and Valuable Stuff. This Valuable Stuff is 
composed of things that you definitely do not want to change. When changed, the 
68000 finds out, and decides to get back at your program in the most strange and 
wonderful ways. These strange results can range from a System Error all the way to 
erasing hard disks and destroying files. There really is no limit to the havoc that can be 
wreaked. This tends to keep the users on the edge of their seat, but this is not really the 
desired effect. As noted above, it won't necessarily cause traumatic results. A program 
can be doing naughty things and not get caught. This is still a bug that needs to be 
fixed, since it is nearly guaranteed to give different results on different versions of the 
Macintosh. Programs exhibiting schizophrenia have been proven to be less enjoyable 
to use. 


How to avoid being a Niller 


Whenever a program uses pointers and handles, it should ensure that the pointer or 
handle will not be nil. This could be termed defensive programming, since it assumes 
that everyone is out to get the program (which is not far from the truth on the 
Macintosh). You should always check the result of routines that claim to pass back a 
handle. If they pass you back a nil handle, you could get in trouble if you use them. 
Don’t trust the ROM. The following example of a defensive use of a handle involves the 
Resource Manager. The Resource Manager passes back a handle to the resource 
data. There are any number of places where it may be forced to pass back a nil 
handle. For example: 


VAR myRezzie: MyHandile; 


myRezzie := MyHandle (GetResource (myResType, myResNumber)); { could be 


missing...} 


IF myRezzie = nil THEN ErrorHandler('We almost got Nilled') 
ELSE myRezzie**.myRect := newRect; { We know it is OK } 


As another example, think of how handles can be purged from memory in tight memory 
conditions. If a block is marked purgeable, the Memory Manager may throw it away at 
any time. This creates an empty handle. The defensive programmer will always make 
sure that the handles being used are not empty. 


VAR myRezzie: myHandle; 


myRezzie := myHandle (GetResource (myResType, myResNumber)); { could be 
: missing.. } 
IF myRezzie = nil THEN ErrorHandler('We almost got Nilled') 


ELSE myRezzie^^.myRect := newRect; { We know it is OK } 
tempHandle := NewHandle {largeBlock); {might dispose a purgeable myRezzie} 
IF myRezzie* = nil THEN LoadResource (Handle (myRezzie)); {Re-load empty 


handle} 
IF ResError = noErr THEN 
myRezzie**.StatusField := OK; { guaranteed not empty, and actually 
gets read back in, if necessary } 


Be especially careful of places where memory is being allocated. The NewHandle and 
NewPtr Calls will return a nil handle or pointer if there is not enough memory. If you 
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use that handle or pointer without checking, you will be guilty of being a Niller. 
How to find Nillers 


The best way to find these nasty ni1 pointer problems is to set memory location zero to 
be an odd number (a good choice is ‘NIL!’ = $4£494C21, which is numerically odd, as 
well as personality-wise). Please see Technical Note #7 for details on how to do this. 


If you use TMON, you can use the extended user area with Discipline. Discipline will 
set memory location 0 to 'NIL! to help catch those nasty pointer problems. If you use 
Macsbug, just type SM 0 'NIL! and go. Realize of course, that if a program has made 
a transgression and is actually using nil pointers, this may make the program crash 
with an ID=2 system error. This is good! This means that you have found a bug that 
may have been causing you untold grief. Once you know where a program crashes, it 
is usually very easy to use a debugger to find where the error is in the source code. 
When the program is compiled, turn on the debugging labels (usually a $D+ option). 
set memory location 0 to be 'NIL!. When the program crashes, look at where the 
program is executing and see what routine it was in (from a disassembly). Go back to 
that routine in the source code and remove the offending code with a grim smile on 
your face. Another scurvy bug has been vanquished. The intoxicating smell of victory 
wafts around your head. $ 
Another way to find problems is to use a debugger to do a checksum on the first four 
bytes in memory (from O to 3 inclusive}. If the program ever traps into the debugger 
claiming that the memory changed, see which part of the program altered memory 
location 0. Any code that writes to memory location zero is guilty of high treason 
against the state and must be removed. Remember to say, “bugs are not my friends.” 
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Creating or Using Fake Handles 


A fake handle is one that was not manufactured by the system, but was created by the 
program itself. An example of a fake handle is: 


CONST aMem = $100; 
VAR myHandle: Handle; 
myPointer: Ptr; 


myPointer := Ptr (aMem); { the address of some memory } 
myHandle := @myPointer; {the address of the pointer variable. Very bad. } 


The normal way to create and use handles is to call the Memory Manager NewHandle 
function. 


Why it’s Bad 


A handle that is manufactured by the program is not a legitimate handle as far as the 
operating system is concerned. Passing a fake handle to routines that use handles is a 
good way to discover the meaning of “Death by ROM.” For example, think how 
confused the operating system would get if the fake handle were passed to 
DisposHandle. What would it dispose? It never allocated the memory, so how can it 
release it? Programs that manufacture handles may find that the operating system is 
no longer their friend. 


When handles are passed to various ROM routines, there is no telling what sorts of 
things will be done to the handle. There are any number of normal handle 
manipulation calls that the ROM may use, such as SetHandleSize, HLock, HNoPurge, 
MoveHHi and so on. Since a program cannot guarantee that the ROM will not be doing 
things like this to handles that the program passes in, it is wise to make sure that a real 
handle is being used, so that all these type of operations will work as the ROM expects. 
For fake handles, the calls like HLock and SetHandleSize have no bearing. Fake 
handles are very easy to create, and they are very bad for the health of otherwise 
upstanding programs. Whenever you need a handle, get one from the Memory 
Manager. 


As a particularly bad use of a fake handle: 


VAR myHandle: Handle; 
myStuff: myRecord; 


myHandle := NewHandle (SIZEOF (myStuff) ); { create a new normal handle } 
myHandle* := @myStuff; {YOW! Intended to make myHandle a handle to 
the myStuff record. What it really does is 
blow up a Master Pointer block, Heap corruption, 
and death by Bad Heap. Never do this. } 


This can be a little confusing, since it is fine to use your own pointers, but very bad to 
use your own handles. The difference is that handies can move in memory, and 
pointers cannot, hence the pointers are not dangerous. This does not mean you 
should use pointers for everything since that causes other problems. It merely means 
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that you have to be careful how you use the handles. 

The use of fake handles usually causes system errors, but can be somewhat 
mysterious in its effects. Fake handles can be particularly hard to track down since they 
often cause damage that is not uncovered for many minutes of use. Any use of fake 
handles that causes the heap to be altered will usually crash the system. Heap 
corruption is a common failure mode. In clinical studies, 9 out of 10 programmers 
recommend uncorrupted heaps to their users who use heaps. 


How to avoid being a fakir 


The correct way to make a handle to some data is to make a copy of the data: 


VAR myHandle: Handle; 
myStuff: myRecord; 


errCode := PtrToHand (@myStuff, myHandle, SIZEOF (myStuff) ); 
IF errCode <> noErr THEN ErrorHandler (‘Out of memory'); 


Always, always, let the Memory Manager perform operations with handles. Never write 
code that assigns something to a master pointer, like: 


VAR myDeath: Handle; 
myDeath* := stuff; { Don’t change the Master pointer. } 


lf there is code like this, it usually means the heap is being corrupted, or a fake handle 
is being used. It is, however, OK to pass around the handle itself, like: 


myCopyHandle := myHandie; { perfectly OK, nobody will yell about this. } 


This is far different than using the * operator to accidentally modify things in the system. 
Whenever it is necessary to write code to use handles, be careful. Watch things 
carefully as they are being written. It is much easier to be careful on the way in than it is 
to try to find out why something is crashing. Be very careful of the @ operator. This 
operator can unleash untold problems upon unsuspecting programs. If at all possible, 
try to avoid using it, but if it is necessary, be absolutely sure you know what it is doing. 
It is particularly dangerous since it turns off the norma! type checking that can help you 
find errors (in Pascal). In short, don’t get crazy with pointer and handle manipulations, 
and they won't get crazy with you. 


How to find fakirs 


Problems of this form are particularly insidious because it can be very difficult to find 
them after they have been created. They tend to not crash immediately, but rather to 
crash sometime long after the real damage has been done. The best way to find these 
problems is to run the program with Discipline. (Discipline is a programmer's tool that 
will check all parameters passed to the ROM to see if they are legitimate. Discipline 
can be found as a stand-alone tool, but the most up-to-date version will be found in the 
Extended User Area for the TMON debugger. The User Area is public domain, but 
TMON itself is not. TMON has a number of other useful features, and is well worth the 
price.) Discipline will check handles that are passed to the ROM to see if they are real 
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handles or not, and if not, will stop the program at the offending call. This can lead you 
back to the source at a point that may be close to where the bad handle was created. If 
a program passes the Discipline test, it will be a healthy, robust program with drastically 
improved odds for compatibility. Programs that do not pass Discipline can sleep poorly 
at night, Knowing that they have broken at least one or two of the “rules.” 


A way to find programs that are damaging the heap is to use a debugger (TMON or 
Macsbug) and turn on the Heap Check operation. This will check the heap for errors at 
each trap call, and if the heap is corrupted will break into the debugger. Hopefully this 
will be close to where the code is that caused the damage. Unfortunately, it may not be 
close enough; this will force you to look further back. 


Looking in the source code, look for all uses of the @ operator, and examine the code 
carefully to see if it is breaking the rules. If it is, change it to step in line with the rest of 
the happy programs here in happy valley. Also, look for any code that changes a 
master pointer like the myHandle* := stuff. Any code of this form is highly suspect, 
and probably a member of the Anti-Productivity League. The APL has been accused of 
preventing software sales and the rise of the Yen. These problems can be quite difficult 
to find at times, but don’t give up. These fake handles are high on the list of guilty 
parties, and should never be trusted. 


Technical Note #117 pagei9 of 28 Compatibility: Why & How 


Writing code that modifies itself 


Self-modifying code is software that changes itself. Code that alters itself runs into two 
main groupings: code that modifies the code itself and code that changes the block the 
code is stored in. Copy protection code often modifies the code itself, to change the 
way it operates (concealing the meaning of what the code does). Changing the code 
itself is very tricky, and also prone to having problems, particularly when the 
microprocessor itself changes. There are third-party upgrades available that add a 
68020 to a Macintosh. Because of the 68020’s cache, programs that modify 
themselves stand a good chance of having problems when run on a 68020. This isa 
compatibility point that should not be missed (nudge, nudge, wink, wink). Code that 
changes other code (or itself) is prone to be incompatible when the microprocessor 
changes. 


The second group is code that changes the block that the code is stored in. Keeping 
variables in the CODE segment itself is an example of this. This is uncommon with 
high-level languages, but it is easy to do in assembly language (using the DC 
directive). Variables defined in the code itself should be read-only (constants). Code 
that modifies itself has signed a tacit agreement that says “I’m being tricky, if | die, I'll 
revise it.” 


Why it’s Bad 


There are now three different versions of the microprocessor, the 68000, 68010, and 
the 68020. They are intended to be compatible with each other, but may not be 
compatible with code that modifies itself. As the Macintosh evolves, the system may 
have compatibility problems with programs that try to “push the envelope.” 


How to avoid being an abuser 


Well, the obvious answer is to avoid writing self-modifying code. If you fee! obliged to 
write self-modifying code, then you are taking an oath to not complain when you break 
in the future. But don’t worry about accidentally taking the oath: you won't do it without 
knowing it. If you choose to abuse, you also agree to personal visits from the Apple 
thought police, who will be hired as soon as we find out. 


How to find abusers 
Run the program on a 68020 system. If it fails, it could be related to this problem, but 
since there are other bugs that might cause failures, it is not guaranteed to be a 


self-modifying code problem. Self-modifying code is often used in copy protection, 
which brings us to the next big topic. 
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Code designed strictly as copy protection . 


Copy protection is used to make it difficult to make copies of a program. The basic 
premise is to make it impossible to copy a program with the Finder. This will not be a 
discussion as to the pros and cons of copy protection. Everyone has an opinion. This 
will be a description of reality, as it relates to compatibility. 


Why it’s Bad 


System changes will never be made merely to cause copy protection schemes to fail, 
but given the choice between improving the system and making a copy protection 
scheme remain compatible, the system improvement will always be chosen. 


e Copy protection is number one on the list of why programs fail the compatibility test. 

* Copy protection by its very nature tends to do the most “illegal” things. 

* Programs that are copy protected are assumed to have signed a tacit agreement to 
revise the program when the system changes. 


Copy protection itself is not necessarily bad. What is bad is when programs that would 
otherwise be fully compatible do not work due only to the copy protection. This is very 
sad, since it requires extra work, revisions to the software, and time lost while the 
revision is being produced. The users are not generally humored when they can no 
longer use their programs. Copy protection schemes that fail generally cause system 
errors when they are run. They also can refuse to run when they should. 


How to avoid being a protectionist 


The simple answer is to do without copy protection altogether. If you think of 
compatibility as a probability game, if you leave out the copy protection, your odds of 
winning skyrocket. As noted above, copy protection is the single biggest reason why 
programs fail on the various versions of the Macintosh. For those who are required to 
use copy protection, try to rely on schemes that do not require specific hardware and 
make sure that the scheme used is not performing illegal operations. If a program runs, 
an experienced Macintosh programmer armed with a debugger can probably make a 
copy of it, (no matter how sophisticated the copy protection scheme) so a moderate 
scheme that does not break the rules is probably a better compatibility bet. The trickier 
and more devious the scheme, the higher the chance of breaking a rule. Tread lightly. 


How to find protectionists 


The easiest way to see if a scheme is being overly tricky is to run it on a Macintosh XL. 
Since the floppy disk hardware is different this will usually demonstrate an unwanted 
hardware dependency. Be wary of schemes that don’t allow installation on a hard disk. 
lf the program cannot be installed on a hard disk, it may be relying upon things that are 
prone to change. Don't use schemes that access the hardware directly. All Macintosh 
software should go through the various managers in the ROM to maintain compatibility. 
Any code that sidesteps the ROM will be viewed as having said “It’s OK to make me 
revise myself.” 
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Check errors returned as function results 


All of the Operating System functions, as well as some of the Toolbox functions, will 
return result codes as the value of the function. Don’t ignore these result codes. If a 
program ignores the result codes, it is possible to have any number of bad things 
happen to the program. The result code is there to tell the program that something 
went wrong; if the program ignores the fact that something is wrong, that program will 
probably be killed by whatever went wrong. (Bugs do not like to be ignored.) Ifa 
program checks errors, an anomaly can be nipped in the bud, before something really 
bizarre happens. 


Why it’s Bad 


A program that ignores result codes is skipping valuable information. This information 
can often prevent a program from crashing and keep it from losing data. 


How to avoid becoming a skipper 


Always write code that is defensive. Assume that everyone and everything is out to kill 
you. Trust no one. An example of error checking is: 


myRezzie := GetResource (myResType, myResId) ; 
IF myRezzie = nil THEN ErrorHandler ('Who stole my resource...'); 


Another example: 


fsErrCode := FSOpen ('MyFile', myVRefNum, myFileRefNum) ; 
IF fsErrCode <> noErr THEN ErrorHandler (fsErrCode, 'File error'); 


And another: 


myTPPrPort := PrOpenDoc (myTHPrint, nil, nil); 
IF PRError <> noErr THEN ErrorHandler (PRError, ‘Printing error’); 


Any use of Operating System functions should presume that something nasty can 
happen, and have code to handle the nasty situations. Printing calls, File Manager 
calls, Resource Manager calls, and Memory Manager calls are all examples of 
Operating System functions that should be watched for returning errors. Always, 
always check the result codes from Memory Manager calls. Big memory machines are 
pretty common now, and it is easy to get cavalier about memory, but realize that 
someone will always want to run the program under Switcher, or on smaller 
Macintoshes. It never hurts to check, and always hurts to ignore it. 


How to find skippers 
This is easy: just do weird things while the program is running. Put in locked or 
unformatted disks while the program is running. Use unconventional command 


sequences. Run out of disk space. Run on 128K Macintoshes to see how the program 
deals with running out of memory. Run under Switcher for the same reason. 
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(Programs that die while running under Switcher are often not Switcher’s fault, and are 
in fact due to faulty memory management.) Print with no printer connected to the 
Macintosh. Pop disks out of the drives with the Command-Shift sequence, and see if 
the program can deal with no disk. When a disk-switch dialog comes up, press 
Command-period to pass back an error to the requesting program (128K ROMs only). 
Torturing otherwise well- behaved programs can be quite enjoyable, and a number of 
users enjoy torturing the program as much as the program enjoys torturing them. For 
the truly malicious, run the debugger and alter error codes as they come back from 
various routines. Sure it’s a dirty low-down rotten thing to do to a program, but we want 
to see how far we can push the program. (This is also a good way to check your error 
handling.) It’s one thing to be an optimist, but it's quite another to assume that nothing 
will go wrong while a program is running. 
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Accessing hardware directly 


Sometimes it is necessary to go directly to the Macintosh hardware to accomplish a 
specific task for which there is no ROM support. Early hard disks that used the serial 
ports had no ROM support. Those disks needed to use the SCC chip (the 8530 
communication chip) in a high-speed clocked fashion. Although it is a valid function, it 
is not something that is supported in the ROM. It was therefore necessary to go play 
with the SCC chip directly, setting and testing various hardware registers in the chip 
itself. Another example of a valid function that has no ROM support is the use of the 
alternate video page for page-flipping animation. Since there is no ROM call to flip 
pages, it is necessary to go play with the right bit in the VIA chip (6522 Versatile 
Interface Adapter). Going directly to the hardware does not automatically throw a 
program into the incompatible group, but it certainly lowers its odds. 


Why it’s bad 


Going directly to the hardware poses any number of problems for enlightened 
programs that are trying to maintain compatibility across the various versions of the 
Macintosh. On the Macintosh XL for example, a lot of the hardware is found in different 
locations, and in some cases the hardware doesn't exist. On the XL there is no sound 
chip. Programs that go directly to the sound hardware will find they don’t work correctly 
on an XL. If the same program were to go through the Sound Manager, it would work 
fine, although the sound would not be the same as expected. Since the Macintosh is 
heavily oriented to the software side of things, expecting various hardware to always be 
available is not a safe bet. Choosy programmers choose to leave the hardware to the 
ROM. 


How to avoid having a hard attack 


Don’t read or write the hardware. Exhaust every possible conventional approach 
before deciding to really get down and dirty. If there is a Manager in the ROM for the 
operation you wish to perform, it is far better to use the Manager than to go directly to 
the hardware. Compatibility at the hardware level can very rarely be maintained, but 
compatibility at the Manager level is a prime consideration. If a program is down to the 
last ditch effort, and cannot get the support from the ROM that is desired, then access 
the hardware in an enlightened approach. The really bad way to do it: 


VIA := Pointer (SEFEIFE); { sure it’s the base address today..} 
{ This is bad. Hard-coded number. } 


The with-it, inspired programmer of the eighties does something like: 
TYPE LongPointer = “LongInt; 


VAR VIA: LongPointer; 
VIABase: LongInt; 


VIA := Pointer ($1D4); { the address of the low-memory global. } 


VIABase := VIA%’; { get the low-memory variable’s value } 
{ Now VIABase has the address of the chip } 
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The point here, is that the best way to get the address of a hardware chip is to ask the 
system where it currently is to be found. The system always knows where the pieces of 
the system are, and will always know for every incarnation of the Macintosh. There are 
low-memory global variables for all of the pieces of hardware currently found in the 
Macintosh. This includes the VIA, the SCC, the Sound Chip, the IWM, and the video 
display. Whenever you are stuck with going to the hardware, use the low-memory 
globals. The fact that a program goes directly to the hardware means that it is risking 
imminent incompatibility, but using the low-memory global will ensure that the program 
has the best odds. It’s like going to Las Vegas: if you don’t gamble at all, you dont 
lose any money; if you have to gamble, play the game that you lose the least on. 


How to find hard attacks 


Run the suspicious program on the Macintosh XL. Nearly all of the hardware is in a 
different memory location on the XL. If a program has a hard-coded hardware address 
in it, it will fail. It may crash, or it might not perform the desired task, but it won’t work as 
advertised. This unfortunately, is not a completely legitimate test, since the XL does not 
have some of the hardware of other Macintoshes, and some of the hardware that is 
there has the register mapping different. This means that it is possible to play by the 
rule of using the low-memory global and still be incompatible. 
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Don’t use bits that are reserved 


Occasionally during the life of a Macintosh programmer, there comes a time when it is 
necessary to bite the bullet and use a low-memory global. These are very sad days, 
since it has been demonstrated (by history) that low-memory global variables are a 
mysterious lot, and not altogether friendly. One fellow in particular is known as ROM85, 
a word located at $285. This particular variable has been documented as the way to 
determine if a program is running on the 128K ROMs or not. Notably, the top most bit of 
that word is the determining bit. This means that the rest of the bits in that word are 
reserved, since nothing is described about any further bits. Remember, if it doesn’t say, 
assume it’s reserved. If it's reserved, don’t depend upon it. Take the cautious way out 
and assume that the other bits that aren't documented are used for Switcher local 
variables, or something equally wild. An example of a bad way to do the comparison 
is: 


VAR Romé5Ptr: WordPtr; 
RomsAre64: Boolean; 


Rom85Ptr := Pointer ($28E); { point at the low-memory global } 
IF Rom85Ptr* = S7FFF THEN RomsAre64 := False { Bad test. } 
ELSE RomsAre64 := True; 


This is a bad test since the comparison is testing the value of all of the bits, not only the 
one that is valid. Since the other bits are undocumented, it is impossible to know what 
they are used for. Assume they are used for something that is arbitrarily random, and 
take the safe way out. 


How to avoid being bitten 


VAR ROM85Ptr: Ptr 


Rom85Ptr := Pointer ($28E); { point at the low-memory global } 
IF BitTst (ROM85Ptr,0) THEN RomsAre64 := True {Good--tests only hi-bit)} 
ELSE RomsAre64 := False; 


This technique will ensure that when those bits are documented, your program won't 
be using them for the wrong things. Beware of trojan bits. 


Don’t use undocumented stuff. Be very careful when you use anything out of the 
Ordinary stream of a high-level language. For instance, in the RoM85 case, it is very 
easy to make the mistake of checking for an absolute value instead of testing the actual 
bit that encodes the information. Whenever a program is using low-memory globals, be 
sure that only the information desired is being used, and not some undocumented (and 
hence reserved) bits. It’s not always easy to determine what is reserved and what isn't, 
so conservative programmers always use as little as possible. Be wary of the strange 
bits, and accept rides from none of them. The ride you take might cause you to revise 
your program. 


How to find those bitten 


Since there are such a multitude of possible places to get killed, there is no simple way 
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to see what programs are using illegal bits. As time goes by it will be possible to find 
more of these cases by running on various versions of the Macintosh, but there will 
probably never be a comprehensive way of finding out who is accepting strange rides, 
and who is not. Whenever the use of a bit changes from reserved status to active, it will 
be possible to find those bugs via extensive testing. From a source level, it would be 
advisable to look over any use of low-memory globals, and eye them closely for 
inappropriate bit usage. Do a global search for the $ (which describes those 
ubiquitous hexadecimal numbers), and when found see if the use of the number is 
appropriate. Trust no one that is not known. If they are documented, they will stay 
where they are, and have the same meaning. Be very carefu! in realms that are 
undocumented. Bits that suddenly jump from reserved to active status have been 
known to cause more than one program to have a sudden anxiety attack. It is very 
unnerving to watch a program go from calm and reassuring to rabid status. Users have 
been known to drop their keyboards in sudden shock (which is bad on the keyboards). 


Technical Note #117 pageo7 of 28 Compatibility: Why & How 


Summary 


So what does ail this mean? It means that it is getting harder and harder to get away 
with minor bugs in programs. The minor bugs of yesterday are the major ones of today. 
No one will yell at you for having bugs in your program, since all programs have bugs 
of one form or another. The goal should be to make the programs run as smoothly and 
effortlessly as possible. The end-users will never object to bug-reduced programs. 


What is the best way to test a program? A reasonably comprehensive test is to 
exercise all of the program’s functions under the following situations: 


e Use Discipline to be sure the program does not pass illegal things to the ROM. 

¢ Use heap scramble and heap purge to be sure that handles are being used 
correctly, and that the memory management of the program is correct. 

¢« Run with a checksum on memory locations 0...3 to see if the program writes to these 
locations. 

¢ Run on a 128K Macintosh, or under Switcher with a small partition, to see how the 
program deals with memory-critical situations. 

¢ Run on a 68020 system to see if the program is 68020-compatible and to make sure 
that changing system speed won't confuse the program. 

e Run ona Macintosh XL to be sure that the program does not assume too much about 
the operating system, and to test screen handling. 

¢ Run on an Ultra-Large screen to be sure that the screen handling is correct, and that 
there are no hard-coded screen dimensions. 

e Run on 64K ROM machines to be sure new traps are not being used when they don’t 
exist. 

+ Run under both HFS and MFS to be sure that the program deals with the file system 
correctly. (400K floppies are usually MFS.) 


If a program can live through all of this with no Discipline traps, no checksum breaks, 
no system errors, no anomalies, no data loss and still get useful work done, then you 
deserve a gold medal for programming excellence. Maybe even an extra medal for 
conduct above and beyond the call of duty. In any case, you will know that you have 
done your job about as well as it can be done, with today’s version of the rules, and 
today’s programming tools. 


Sounds like a foreboding task, doesn’t it? The engineers in Macintosh Technical 
Support are available to help you with compatibility issues (we won't always be able to 
talk about new products, since we love our jobs, but we can give you some hints about 
compatibility with what the future holds). 


Good luck. 
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#118: How to Check and Handle Printing Errors 
see also: The Printing Manager 


Written by: Ginger Jernigan May 4, 1987 


This technical note describes how to check and properly handle errors that 
occur during printing. 


Most people are aware of the need for checking File Manager errors, Resource 
Manager errors, and the like, but sometimes Printing Manager errors get neglected; 
you should always check for error conditions while printing. This can be done by calling 
PrError. Errors returned by PrError will include any Printing Manager errors (and 
some AppleTalk and OS errors) that occur during printing. 


The best place to start is with the code fragment listed on page II-155 in Inside 
Macintosh: 


myPrPort :* PrOpenDoc (prRecHdl, NIL, NIL); { open printing grafPort } 


FOR pg := 1 TO myPgCount DO {page loop: ALL pages of document] 
IF PrError = noErr 
THEN 
BEGIN 
PrOpenPage (myPrPort, NIL); . {start new page} 
IF PrError = noErr 
THEN MyDrawingProc (pg); {draw page with QuickDraw} 
PrClosePage (myPrPort); {end current page} 
END; 


PrCloseDoc (myPrPort) ; 
IF prRecHdl**.prJob.bJDocLoop = bSpoolLoop AND PrError = noErr 


THEN 
BEGIN 
MySwapOutProc; {swap out code and data} 
PrPicFile (prRecHd1,NIL,NIL,NIL,myStRec); {print spooled document} 
END; 


IF PrError <> noErr THEN MyPrErrAlertProc; {report any errors} 

Here are some error-handling guidelines: 

e You should avoid calling PrError within your PrIdile procedure; errors that occur 
while it is executing are usually temporary and serve only as internal flags for 


communication within the printer driver-—they are not intended for the application. If 
you absolutely must call PrError within your idle procedure, and an error occurs, 
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never abort printing within the idle procedure itself. Wait until the last called printing 
procedure returns and then check to see if the error still remains. Attempting to abort 
printing within an idle procedure is a guarantee of certain death. 


e if you detect that an error has occurred after the completion of a printing routine, just 
stop where you are, i. e. stop drawing. Proceed to the next print procedure fo close 
any open calls you have made. For example, if you called PrOpenDoc and received 
an error, skip to the next PrCloseDoc. Or if you called PrOpenPage and got an error, 
skip to the next PrClosePage and PrCloseDoc. Remember that if some PrOpen... 
procedure has been called, then you must call the corresponding PrClose... 
procedure to ensure that printing closes properly and that all temporary memory 
allocations are released and returned to the heap. 


¢ Do not raise any alerts or dialogs to report an error until the end of the print loop. At 
the end of the print loop, check for the error again; if there is no error assume that 
printing completed normally. If it’s still there, you can raise an alert. 


This is important for two reasons. First, if an alert is raised in the middle of the print 
loop, it can cause errors that will terminate an otherwise normal job. For example, if 
the printer is an AppleTalk printer, the connection can be terminated abnormally. 
While your alert is sitting there waiting for a response from the user, the driver is 
unable to respond to AppleTalk requests coming in from the printer. If the printer 
doesn't hear from the Macintosh within a short time period (30 seconds) then it will 
timeout, assuming that the Macintosh is no longer there. This results in the 
connection being broken prematurely causing another error that the application has 
to respond to. 


The driver may also have already put up its own alert in response to the error. In this 
instance, the driver will post an error to let your application know that something went 
wrong and that it’s time to abort printing. For example, when the driver detects that 
the version of Laser Prep that has been downloaded to the LaserWriter is different 
from the version that the user is trying to print with, the LaserWriter driver raises the 
appropriate alert telling the user that the printer was initialized with an incompatible 
version of the driver and gives the option of reinitializing. If the user chooses to 
cancel, the driver posts an error to let the application know that it needs to abort, but 
since the driver has already taken care of the error by putting up an alert, the error is 
reset to zero before the printing loop is complete. The application should check for 
the error again at the end of the printing loop and if it stil! indicates an error, it should 
raise an alert. 
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#119: Determining If Color QuickDraw Exists 


See also: QuickDraw 
Technical Note # 129—SysEnvirons 


Written by: Jim Friedlander May 4, 1987 





The next system release will include a new SysEnvirons Call that will tell an 
application, among other things, if Color QuickDraw exists. For now, you can test to 
see if at least the two high bits of the low-memory global Roms5 (word at $285) are 
clear—if so, then Color QuickDraw exists. 


From MPW Pascal: 


TYPE 
WordPtr = “Integer; 


CONST 
ROM85Loc = $28E; 
TwoHighMask = $C000; {mask for two high bits} 


FUNCTION ColorQDExists: Boolean; 


Begin { ColorQDExists } 
ColorQDExists:= BAND (WordPtr (Rom85Loc) *, TwoHighMask) = 0; 
{non-MPW Pascals can use the ToolBox routine 'BitAnd" above} 
End; { ColorQDExists } 


From MPW C: 


#define ROM85 (*(short *)0x28e) 
#define TWOHIGHMASK 0xc000 
#define COLORQDEXISTS ! (ROM85 & TWOHIGHMASK) 


if (COLORQDEXISTS) /* test for Color QuickDraw * f 
/* Color QD exists ... */? 

elise 
/* no color QD ... */; 
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#120: Drawing Into an Offscreen PixMap 


See also: QuickDraw 
Technical Note #41—Drawing Into an Offscreen Bitmap 
Technical Note #119—Determining If Color QuickDraw 
Exists 
Technical Note #129—SysEnvirons 


Written by: Jim Friedlander & Rick Blair May 4, 1987 
Modified by: Rick Blair July 1, 1987 





This technical note provides a simple example of drawing to, then copying 
from, an offscreen PixMap. Changes since 5/87: Set theGDevice to the 
MaxDevice before the OpencPort Call to get more of the PixMap set up 
correctly. This saves code and, more importantly, improves its chances of 
being compatible in the future. Secondly, fixed a typo in the offRowBytes 
calculation. 





This example shows how to draw something in an offscreen PixMap and then CopyBits 
it back to the screen. It handles the case where multiple screens of different pixel depths 
are present. 


Before we can make any Color QuickDraw calls, we must be sure that Color QuickDraw 
is present (see Technical Notes #119 and #129 for details). Then, given the following 
types, constants and variables: 


CONST 
OffLeft = 30; 
OffTop = 30; 
OoffBottom = 250; 
offRight = 400; 


{These constants for the bounds of the offscreen PixMap are chosen 
because we know what the extent of the drawing will be and we want to 
restrict the size of the map as much as possible. } 


TYPE 

BitMapPtr = “BitMap; {for type coercion in the CopyBits call} 
VAR 

offRowBytes : Longint; 

sizeOfoft : Longint; 

myBits : Ptr; 

destRect : Rect; 
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globRect : Rect; 
bRect >: Rect; 
theDepth : INTEGER; 

i : INTEGER; 
err ¿< INTEGER; 
myCGrafPort : CGrafPort; 
myCGrafPtr : CGrafPtr; 
ourCMHandle : CTabHandle; 
theMaxDevice : GDHandle; 
oldDevice : GDHandie; 


we first create a color window: 
myCWindow := GetNewCWindow(SomeID, NIL, WindowPtr (-1)); 


First we need to find the maximum depth device to which we will be CopyBitsing the 
offscreen image: 


SetPort (myCWindow); {set to this port for the localToGlobals that 
follow} 
SetRect (bRect, OffLeft, OffTop, OffRight, OF fBottom) ; 
IF NOT SectRect (myCWindow’.portRect,bRect,globRect) THEN 
NothingToCopy; {nothing to do, clean up and EXIT} 


{still here, so let’s convert to globals} 
LocalToGlobal (globRect .topLeft) ; 
LocalToGlobal (globRect .botRight) ; 


{figure out how much space we need for our pixel image. 
we will call GetMaxDevice and get the pixel map from that -- 


we do this to cover the case where the pixel image that we wish 
to CopyBits to spans multiple devices (of possibly different depths) } 


theMaxDevice:= GetMaxDevice (globRect); {get the maxDevice} 


Now we need to set theGDevice to the device with the maximum pixel depth, so that the 
pixel map of our new CGrafPort will be copied from one of the proper depth, etc.: 


oldDevice := GetGDevice; {save theGDevice so we can restore it later} 
SetGDevice (theMaxDevice) ; {Set to the maxdevice} 


then we open a new CGrafPort which will be used for offscreen drawing: 


myCGrafPtr := @myCGrafPort; {initialize this guy} 
OpenCPort (myCGrafPtr); {open a new color port — this calls InitCPort} 


theDepth:= myCGrafPtr*.portPixMap*%*.pixelSize; 
Now we're ready to calculate the size of the pixel image that we'll need: 


{similar formula to technote 41, except we must include pixel depth} 
offRowBytes := ((((theDepth * (OffRight - OffLeft)) + 15)) DIV 16) * 2; 
{make sure LongInt math is done on the next line! } | 

sizeOfOff := Longint (OffBottom - OffTop) * offRowBytes; ` 

oOffSetRect (bRect, ~ OffLeft, - OffTop); {adjust for local coordinates} 
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{Set up baseAddr, rowBytes,bounds and pixelSize of the PixMap in our 
fresh, new CPort} 

myBits := NewPtr(sizeOfOff); {allocate space for the pixel image} 

{real programs do error checking here} 


Now to fix up the PixMap location- and size-specific information: 


WITH myCGrafPtr*.portPixMap”* DO BEGIN 
baseAddr := myBits; 
rowbytes := offRowBytes + $8000; {remember to be new PixMap} 
bounds := bRect; | 

END; {with} 


Color QuickDraw distinguishes between new and old style ports by checking the high bit 
of rowBytes, which is why we add $8000 to Of fRowBytes in the above code. Now we 
need to clone the maxDevice’s color table so we can put it into our offscreen PixMap. 
We also need to convert it from a color table for a device to a color table for a PixMap (in 
case we are CopyBitsing into a picture): 


ourCMHandle := theMaxDevice**.gdPMap**.pmTable; 
err := HandToHand (Handle (ourCMHandle)); {clone it} 
{real programs do error checking here} 
{now convert from device color table to PixMap color table-thanks DG!} 
WITH ourCMHandle** DO BEGIN 
FOR i:= 0 TO ctSize DO 
ctTable[i].value:= i; {put in indices} 
{now clear the high bit of transIndex to indicate it’s a PixMap 
color table} 
transIndex:= BAND (transindex, $7FFF) ; 
END; {WITH} 


myCGrafPtr*.portPixMap**.pmTable := ourCMHandle; {put the cloned, 
correctly set-up Color Table into the offscreen map } 
SetPort (GrafPtr(myCGrafPtr)); {Set the port to the offscreen port) 


Now we call procedure Drawit (which calls the function FillInColors) to draw an 
image in the offscreen port: 


FUNCTION FilliInColor(r,g,b: Integer): RGBColor; 
{small utility routine to return an RGBColor} 


VAR 
theColor : RGBColor; 
BEGIN {FillInColor} 
WITH theColor DO BEGIN 
red := r}; 
green := g; 
blue := b; 
END; 
FillInColor := theColor; 
END; {FillInColor} 


PROCEDURE DrawIt; 


VAR 
OvalRect : Rect; 
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myRed,myBlue,myWhite, 
myGreen, myBlack : RGBColor; 


BEGIN { DrawIt } 
{get our colors set up} 
myRed := FillInColor(-1,0,0); 
myBlue := FillInColor(0,0,-1); 
myGreen := FillInColor(0,-1,0); 
myWhite := FiliInColor(-1,-1,-1); 
myBlack := FillInColor(0,0,0); 
PenMode (PatCopy) ; 
RGBBackColor(myBlue); {set the backcolor of the current port] 
EraseRect (thePort*.portRect); {blue it out} 
RGBBackColor (white); {set back to white} 


RGBForeColor (myRed) ; {set the forecolor of the current port} 
SetRect (OvalRect, 30,30,190,150); 
PaintOval (OvalRect) ; 


InsetRect (OvalRect,1,20); 
EraseOval (OvalRect); {erase oval to white} 


RGBForeColor (myGreen) ; {draw the final oval in green} 
InsetRect (OvalRect, 40,1); 
PaintOval (OvalRect) ; 
RGBForeColor (myBlack) ; 
END; { DrawIt } 


Now we're done drawing, so set thePort and theGDevice back: 


SetPort (MyCWindow) ; 
SetGDevice (oldDevice) ; 


Now we can draw the image onscreen by CopyBitsing the bits from the offscreen 
PixMap’s portPix tO MyCWindow’s portPix: 


destRect := bRect; 

OffSetRect (destRect, OffLeft,OffTop); {adjust for coordinates} 

CopyBits (BitMapPtr (MyCGrafPtr*.portPixMap*)*, MyCWindow*.portBits, 
bRect, destRect, 0, NIL); 


and, finally, we clean up by closing the CGrafPort we created, freeing the space we 
reserved for the offscreen PixMap’s pixel image and disposing of the color table we 
allocated: 


CloseCPort (myCGrafPtr) ; {Close our port) 


DisposPtr (MyBits) ; {clean up} 
DisposHandle (Handle (ourCMHandle)); {get rid of color table we cloned} 


Note: For optimal performance, you will want to make sure that the source and 
destination PixMaps are aligned—this will be the subject of a future technical note. 
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#121: Using the High-Level AppleTalk Routines 
See also: The AppleTalk Manager 
Inside AppleTalk 
APDA Macintosh AppleTalk Update 


Written by: Fred A. Huxham May 4, 1987 





What you need to do in order to use the high-level AppleTalk routines 
depends upon the version of the interfaces you are using. The necessary 
steps are outlined below. 


i a aaaaaaaIaaaaaaaaaaaaIaIaMuMuassssasasaastlutlasssssssssssstllu$llllllllllllllMMlMMl— 


interface version 3.4 


When calling the high-level AppleTalk routines, many programmers got mysterious 
“resource not found” errors (-192) from such seemingly harmless routines as MPPOpen. 
The resource that is not being found is ‘atpl', a resource that contains all the glue code 
to the high-level routines. In order to use the high-level routines, your application must 
have this resource in its resource fork. The ‘atpl’ resource can be found in the 
AppleTalk file which is in the Libraries folder of MPW. 


Interface version 4.0 


The 4.0 interface is available from APDA as the Macintosh AppleTalk Update and in 
MPW 2.0b1 (also available through APDA); it includes bug fixes and increased 
Macintosh II compatibility. See the APDA package for more information on the 
differences between these versions. With this version of the interface, the ‘atpl 
resource is no longer needed. The glue code that lived in 'atpl' is now linked into your 
application. 


Also, 4.0 will be the final release of the current-style interface. It will be supported for 
some time. However, in the long run, we plan to move to a more straightforward and 
simple interface design. This new-style interface will be a parameter-block style 
interface, much like the current low-level file system interface detailed in Inside 
Macintosh, volume IV. 


Developers are free to continue to use the old-style interface for Macintosh Plus-style 
AppleTalk functionality, but in the long run it will be advantageous to move to the 
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new-style interface. Most calls will be essentially the same format as the high-level 
XPP calls included with the 4.0 release. 
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#122: Device-Independent Printing 
See also: _ The Printing Manager 


Written by: Ginger Jernigan May 4, 1987 





The Printing Manager was designed to give Macintosh applications a device- 
independent method of printing, but we have provided device-dependent information, 
such as the contents of the print record. Due to the large number of printer-type drivers 
becoming available (even for non-printer devices) device independence is more 
necessary than ever. What this means to you, as a developer, is that we will no longer 
be providing (or supporting) information regarding the internal structure of the print - 
record. : 


We realize that there are situations where the application may know the best method for 
printing a particular document and may want to bypass our dialogs. Unfortunately, using 
your own dialogs or not using the dialogs at all, requires setting the necessary fields in 
the print record yourself. There are a number of problems: 


e Many of the fields in the print record are undocumented, and, as we change the 
internal architecture of the Printing Manager to accommodate new devices, those 
undocumented fields are likely to change. 


+ Each driver uses the private, and many of the public, fields in the print record 
differently. The implications are that you would need intimate knowledge of how 
each field is used by each available driver, and you would have to set the fields in 
the record differently depending on the driver chosen. As the number of available 
printer-type drivers increases, this can become a cumbersome task. 


Summary 
To be compatible with future printer-like devices, it is essential that your application print 
in a device-independent manner. Avoid testing undocumented fields, setting fields in the 


print record directly and bypassing the existing print dialogs. Use the Printing Manager 
dialogs, PrintDefault and Prvalidate to set up the print record for you. 


Technical Note #122 page 1 of1 Device-Independent Printing 


Macintosh Technical Notes $ 


#123: Bugs in LaserWriter ROMs 


See also: The Printing Manager 

PostScript Language Reference Manual, Adobe Systems 
Written by: Ginger Jernigan May 4, 1987 
Modified by: Ginger Jernigan July 1, 1987 


These are LaserWriter bugs that your users may encounter when printing 
from any Macintosh application. These are for your information; you cannot 
code around them. The bugs described here occur in the 1.0 and 2.0 
LaserWriter ROMs. Changes since 5/87: now includes more detailed and 
accurate information about these bugs. 


To determine which ROMs their LaserWriter contains, users can look at the test page that 
the LaserWriter prints at start-up time. in addition to other information (detailed in the 
LaserWriter user's manual), the ROM version is shown at the bottom of the line graph. 
The original LaserWriter contained version 1.0 ROMs. The currently shipping 
LaserWriter and those upgraded to the LaserWriter Plus contain version 2.0 ROMS. 


These are some of the problems we know of: 


1. ifthe level of paper in the paper tray is getting low, and the user prints a document 
that will cause the tray to become empty, a PostScript error may occur. This 
problem exists in both the 1.0 and 2.0 LaserWriter ROMs and will not be fixed in the 
next ROM version. 


2. Ifa user prints more than 15 copies of a document, a timeout condition may occur 
causing the print job to abort. With LaserShare, this problem can occur with as few 
as 9 copies. This problem is a result of the LaserWriter turning AppleTalk off while it 
is printing. It doesn’t send out any packets to tell the world it’s still alive while it is 
printing, so the connection times out after about 2 minutes. This problem exists in 
both the 1.0 and 2.0 LaserWriter ROMs and will not be fixed in the next ROM 
version. 


3. When printing a document that contains more than 10 patterns, users may receive 
intermittent PostScript errors. This usually occurs when trying to print a lot of 
patterns, and a bitmap image on the same page. The code for imaging patterns 
allocates almost all of the available RAM for itself, so when the bitmap imaging code 
tries to allocate space, and there isn’t enough (and it doesn’t know how to reclaim 
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memory from the previous operation), a Limitcheck error occurs. This problem 
exists in 2.0 LaserWriter ROMs. It will be improved but not fixed in the next ROM 
version. 


4. Ifa user chooses US Letter or B5 paper and has a different sized tray in the printer, 
and prints using manual feed, the LaserWriter will print assuming that the paper 
being fed manually is the same size as that in the tray. For example, if they have a 
US letter tray in the LaserWriter and print a document formatted for B5 letter using 
manual feed, the image will not be centered on the page. The printer assumes that 
the manually fed paper is also US letter size and prints the image positioned 
accordingly, despite the driver’s instructions. This is a bug in the Note operator in 
PostScript, which the driver uses for specifying the US letter and B5 letter paper 
sizes. The workaround is to tell the user to put an B5 tray in the printer when 
printing B5 manually. This problem exists in the 1.0 and 2.0 ROMs and will not be 
fixed in the next ROM version. 


By the way, an interesting, but annoying, occurance of this bug happens when 
manually printing Legal sized documents with the 4.0 LaserWriter driver. When the 
Larger Print Area option in the style dialog is deselected (which is the default) the 
driver uses the Note operator to specify the page size. When the user prints the 
document using manual feed, and has a US letter tray in the printer, the image is 
shifted up on the page cutting off the top of the image. If you tell the user to turn on 
the Larger Print Area option in the style dialog, the driver specifies the page size 
using Legal instead of Note and the image is printed properly. 
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#124: Using Low-Level Driver Calls With the AppleTalk ImageWriter 
See also: The Printing Manager 


Written by: Ginger Jernigan May 4, 1987 





When you use the low-level driver to print, you don’t get the benefits of some of the error 
checking that is done when you use the Printing Manager. So, if the user prints to an 
AppleTalk ImageWriter that is busy printing another job, the driver doesn't recognize that 
the printer is busy and it goes ahead and prints. The printer throws these print 
commands away and nothing is printed. 


Since there is no way to tell when you are printing to an AppleTalk ImageWriter, the only 
workaround for this is to avoid the use of low-level printer driver calls. 
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#125: The Effect of Spool-a-page/Print-a-page on Shared Printers 


See also: Printing Manager 
Technical Note #72—Optimizing for the LaserWriter 
—Techniques 

Written by: Ginger Jernigan May 4, 1987 





This technical note discusses the drawbacks of using the spool-a-page/ 
print-a-page method of printing. 





The “spool-a-page/print-a-page” method of printing prints each page of a document as 
a separate job instead of calling PrPicFile to print the entire picture file. Many 
applications adopted this method of printing to avoid running out of disk space while 
the ImageWriter driver was spooling the document to disk. As long as you are printing 
to a directly connected ImageWriter, you're fine, but if you are printing to remote or 
shared devices (like the AppleTalk ImageWriter and the LaserWriter), this method may 
create significant problems for the user. 


When a job is initiated by the application, the driver establishes a connection with the 
printer via AppleTalk. When the job is completed, the driver closes the connection, 
allowing another job the opportunity to print. If each page is a job in itself, then the 
connection is closed and reopened between each page, allowing another application 
to print between the pages of the document, which, as you might imagine, could 
present a significant problem. If two people are printing to the same AppleTalk 
ImageWriter at the same time and their applications use the 
“spool-a-page/print-a-page” method of printing, the pages of each document will be 
interleaved at the printer. 


Although there are good reasons for using this method of printing, it is only useful for a 
directly connected printer. From a compatibility point of view, this method of printing is 
built-in device dependence. Also, this method could create serious problems for other 
types of remote devices. Therefore, we are recommending that applications avoid 
using this method indiscriminately. You should check available disk space to see how 
much room you have before you print. If there isn’t enough space for your entire 
document, then print as much as you can (to minimize the interleaving) before starting 
another job. Whenever possible, applications should use the print loop described on 
page II-155 in the Printing Manager chapter of Inside Macintosh. 
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#126: Sublaunching: Playing the Shell game 
See also: Segment Loader 


Written by: Rick Blair May 4, 1987 
Revised by: Rick Blair & Jim Friedlander July 1, 1987 


Note: Macintosh Technical Support takes the view that this is a feature 
which is best left out for compatibility (and other) reasons, but we want to 
make sure that when it is absolutely necessary to implement it, it is done in 
the safest way. 


Herein is a means to launch an application from your program and have it 
return to you as though you were a “shell,” like the Finder. There are 
unresolved issues, though (and some downright problems), so please read 
the cautionary notes which follow. — 


Changes since 5/87 include advising you to set both high bits of 
LaunchF lags for future compatibility. Throwing away working directories 
that you created is no longer recommended. If you are opening working 
directories, you should make sure to check for errors (t(MWDOErr = —121) 
after calling PBOpenwD. 


Warning 


The interface to the Launch trap will change in the not-too-distant future. When that 
happens, programs which launch other applications will break. You should really only 
consider doing this if you are implementing an integrated development system. 


The Finder does a lot of hidden cleanups and other tasks of which the user isn’t aware. 
Therefore it is best if you don’t try to replace the Finder with a “mini,” or try to launch 
other programs and have them return to your application. In the future the Finder may 
provide better integration for applications and you would circumvent this if you tried to 
take over its role. 
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Nevertheless, consider a text editor that wants to allow the user to run, say, ResEdit, 
and then return to program editing. If it isn’t worried about the transition to new 
environments, then it would want to do this in a way that would fit into the current 
system well. System file version 4.1 (or higher) includes a mechanism for allowing a 
call to another application which we term a sublaunch. This is accomplished with a set 
of simple extensions to the parameter block which is passed to the Launch trap. Note 
that for future compatibility we don't assume that Launch will not return. 


A Sublaunch from Pascal 


{It is assumed that the Signals are caught elsewhere; see Technical 
Note #88 for more information on the Signal mechanism} 


{the extended parameter block to _Launch} 
TYPE 
pLaunchStruct = “LaunchStruct; 
LaunchStruct = record 
pfName: *Str255; 
param: INTEGER; 
LC:PACKED ARRAY[0..1] OF CHAR; {start of extended parameter block} 
ExtBlockLen: LONGINT; {number of bytes in extension = 6} 
fFlags: INTEGER; {Finder file info flags (see below) } 
LaunchFlags: LONGINT; {bits 31,30=1 for sublaunch, 
other bits reserved} 
End; {LaunchStruct} 
VAR 
err: INTEGER; 
pMyLaunch: pLaunchStruct; 
myLaunch: LaunchStruct; 
fName: Str255; 


FUNCTION LaunchIt (pLnch: pLaunchStruct) : INTEGER; {< 0 means error} 
INLINE $205F, SA9F2, $3E80; 
{ pops pointer into AO and calls Launch, pops DO error code into result: 
MOVE.L (A7)+,A0 
_Launch 
MOVE.W DO, (A7) ; since it MAY return in the future} 


PROCEDURE DoLaunch; 


VAR 
wher: Point; { where to display dialog } 
reply: SFReply; { reply record } 
myFileTypes: SFTypeList; { we won’t actually use this } 


NumFileTypes: integer; 
myPB: CInfoPBRec; 
DirNameStr: stxr255; 
BEGIN 
wher.h := 20; 
wher.v := 20; 
NumFileTypes:= -1; {Display all files} 


{ Let the user choose the file to Launch } 
SFGetFile (wher, '', Nil, NumFileTypes, MyFileTypes, NIL, reply); 


IF reply.gqood THEN begin 
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DirNameStr:= reply.fName; {initialize to file selected) 
with MyPB do Begin 

ioCompletion:= NIL; 

ioNamePtr:= @DirNameStr; 

ioVRefNum:= reply. vRefNum; 

ioFDirindex:= 0; 

ioDrDirID:=0 
End; {with MyPB} 


{ Get the Finder flags } 
Signal (PBGetCat Info (@MyPB, FALSE) ); 


{ Set the current volume to where the target application is } 
Signal (SetVol(NIL, reply.vRefNum) ); 


pMyLaunch:= @myLaunch; 
fName:= reply.fName; 
With pMyLaunch^ do Begin 


pfName:= @fName; {pointer to our fileName} 
param:= 0; {we don’t want alternate screen or sound buffers} 
LC := 'LC'; {here to tell Launch that there is non-junk next} 


ExtBlockLen := 6; {length of param. block past this long word} 
{copy flags; set bit 6 of low byte to 1 for RO access: } 
fFlags := MyPB.ioFlFndrinfo.fdFlags; (from GetCatinfo} 
LaunchFlags := $C0000000; {set BOTH hi bits to indicate a 
sublaunch } 
End; {With} 
err := Launchit (pMyLaunch); {launch; we don’t know what error codes 
to expect, so just check for < 0 (which means it failed) } 
IF err < 0 THEN 
Signal(err); {can’t just Signal because we might get a positive code; 
you might want to put up a dialog which explains that 
the selected application couldn’t be launched for some 
reason. } 
end; {IF reply.good} 
End; {DoLaunch} 


Working directories 


Putting aside the compatibility issue for the moment, the only problem this creates 
under the current system is one of Working Directory Control Blocks, or WDCBs. 
Unless the application you are launching is at the root or on an MFS volume, a new 
WDCB must be created so that it may be set as the current directory when the program 
is run. 


In the example procedure above, the new working directory is opened (allocated) by 
Standard File and its WORefNum is returned in reply.vRefNum. If you weren't using 
Standard File and couldn’t assume, for instance, that the application was in the 
blessed folder or root then you would have to open a new working directory explicitly 
via OpenwD. The new WDCB should have a WDProcID of ’ERIK’ so that the Finder or 
another shell that saw that the WDCB had been allocated by a “sublaunchee” would 
know to de-allocate it. 
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The sublaunching process is recursive; you may sublaunch a program which then 
sublaunches another, and so on, and when each application exits it will return to the 
one that called it. The problem is that there is a limit to the number of WDCBs that can 
be created; currently (and probably forever) the limit is 40. You can see how quickly 
these might be used up if many programs were playing the shell game or neglecting to 
de-allocate WDCBs they had created. Make sure that you check for errors after calling 
PBOpenWD. AtMWDOErr (—121) means that all available WOCBs have been allocated. 
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#127: TextEdit EOL Ambiguity 
See also; TextEdit 


Written by: Rick Blair May 4, 1987 





TESetSelect may be used to position the insertion point at the end of a line. 
There is an ambiguity, though; should the insertion point appear at the end 
of the preceding line or the start of the following one? It is possible to 
determine what will happen, as you are about to see. 





There is an internal flag used by TextEdit to determine where the insertion point at the 
end of a line appears. This flag is part of the clikStuff field in the TERec. It is there 
mainly for the use of TEClick, but it is also used by TESet Select (although it defaults 
to the right side of the previous line). 


The following code can be used to force the insertion point to appear at the left of the 
following line when it is positioned at the end of a line: 


TEDeactivate (tH); 

tH^^.clikStuff := 255; {position caret on left} 
TESetSelect (eolcharpos, eolcharpos, tH); {ambiguous point} 
TEActivate (tH); 


If you want to ensure that the caret is on the right side (to which it normally defaults) 
then substitute a zero for the 255. 


Technical Note #127 page 7 of1 TextEdit EOL Ambiguity 





Á 


Macintosh Technica! Notes CS 


#128: PrGeneral 


See also: The Printing Manager 
Technical Note #118: How to Check and Handle Printing 
Errors 

Written by: Ginger Jernigan May 4, 1987 





The Printing Manager architecture has been expanded to include a new 
procedure called prcenerai. The features described here are advanced, 
special-purpose features, intended to solve specific problems for those 
applications that need them. The calls to determine printer resolution 
introduce a good deal of complexity into the application’s code, and should be 
used only when necessary. 





Version 2.5 {and later) of the ImageWriter driver and version 4.0 (and later) of the 
LaserWriter driver implement a generic Printing Manager procedure called PrGeneral. 
This procedure allows the Print Manager to expand in functionality, by allowing the 
printer drivers to implement various new functions. The Pascal declaration of PrGeneral 
is 


PROCEDURE PrGeneral (pData: Ptr); 


The pData parameter is a pointer to a data block. The structure of the data block is 
declared as follows: 


TGn]lData = RECORD {1st 8 bytes are common for all PrGeneral calls); 


iOpCode: Integer; {input } 

iError: Integer; {output } 

lReserved: LongInt; {reserved for future use} 

{more fields here, depending on particular call} 
END; 


The first thing in the data block is a 2-byte opcode, iOpCode, which acts somewhat like a 
routine selector. The currently available opcodes are described below. 


The second field in the record is the error result, iError, which is returned by the print 
code. This error only reflects error conditions that occur during the PrGeneral call. For 
example, if you use an opcode that isn’t implemented in a particular printer driver then 
you will get a OpNot Imp1 error. Here are the errors currently defined: 


CONST 
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NoErr = 0; { everything’s hunky } 
NoSuchRsl i; { the resolution you chose isn’t available } 
OpNot Imp1 2; { the driver doesn’t support this opcode } 


After calling PrGeneral you should always check PrError. If NoErr is returned, then 
you can proceed. If ResNotFound is returned, then the current printer driver doesn't 
support PrGeneral and you should proceed appropriately. See Technical Note #118 for 
details on checking errors returned by the Printing Manager. 


IError is followed by a four byte reserved field (that means don’t use it). The contents of 
the rest of the data block depends on the opcode that the application uses. There are 
currently five opcodes used by the ImageWriter and LaserWriter drivers and they are 
discussed below. 


The Opcodes 
Initially, the following calls are implemented via PrGeneral: 


e GetRslData (get resolution data): iopCode = 4 

e SetRs1 (set resolution): iopCode = 5 

* DraftBits (bitmaps in draft mode): iOpCode = 6 

e noDraftBits (no bitmaps in draft mode): iopCode = 7 
e GetRotn (get rotation): iopCode = 8 


The GetRslData and SetRs1 allow the application to find out what physical resolutions 
the printer supports, and then specify a supported resolution. DraftBits and 
noDraftBits invoke a new feature of the ImageWriter, allowing bitmaps (imaged via 
CopyBits) to be printed in draft mode. GetRotn lets an application know whether 
landscape has been selected. Below is a detailed description of how each opcode 
routine works. 


The GetRs!Data Call 
GetRslData (i0pCode = 4) returns a record that lets the application know what 
resolutions are supported by the current printer. The application can then use SetRs1l 


(description follows) to tell the printer driver which one it will use. 


This is the format of the input data block for the Get Rs1Data Call: 


TRslRg = RECORD {used in TGetRsl1Blk} 
iMin: Integer; {0 if printer only supports discrete resolutions} 
iMax: Integer; {0 if printer only supports discrete resolutions} 
END; 
TRslRec = RECORD {used in TGetRs1Blk} 
iXRsl: Integer; {a discrete, physical X resolution} 
iYyRsl: Integer; {a discrete, physical Y resolution} 
END ; 
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TGetRsliBlk = RECORD {data block for GetRslData call} 


iOpCode: Integer; {input; = getRsiDataOp} 

iError: Integer; {output} 

1Reserved: LongInt; {reserved for future use} 
iRgType: Integer; {output; version number} 

XRS1Rg: TRs1Rg; {output; range of X resolutions} 
YRSIRG: TRs1Rg; {output; range of Y resolutions) 


iRslRecCnt: Integer; {output; how many RslRecs follow} 
rgRslRec: ARRAY{1..27] OF TRslRec; {output; number filled depends on 
printer type} 
END; 


The iRgType field is much like a version number; it determines the interpretation of the 
data that follows. At present, a iRgType value of 1 applies both to the LaserWriter and to 
the ImageWriter. 


For variable-resolution printers like the LaserWriter, the resolution range fields XRs1Rg 
and YRs1Rg express the ranges of values to which the X and Y resolutions can be set. 
For discrete-resolution printers like the ImageWriter, the values in the resolution range 
fields are zero. 


Note: In general, X and Y in these records are the horizontal and vertical directions of 
the printer, not the document! In landscape orientation, X is horizontal on the printer but 
vertical on the document. 


After the resolution range information there is a word which gives the number of 
resolution records that contain information. These records indicate the physical 
resolutions at which the printer can actually print dots. Each resolution record gives an X 
value and a Y value. 


When you call prGeneral you pass in a data block that looks like this: 


OpCode = 4 1 word 
Error Code 1 word 
Reserved 2 words 


RangeType = 1 1 word 


X Resolution Range: 
min = 0, max = 0 2 words 


Y Resolution Range: 2 words 
min #0, max = 0 


Resolution Record Count #0 1 word 


Resolution Record #1: 2 words 


=0,Y= 


Resolution Record #2..27 
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Below is the data block returned for the LaserWriter: 

















wor 
1 wor 
1 wora 
aa 1500 A Wons 
Y Resolution Range: 2 words 
min = 72, max = 1500 
2 words 


Resolution Record #1: 

X = 300, Y = 300 

Note that all the resolution range numbers happen to be the same for this printer. There 
is only one resolution record, which gives the physical X and Y resolutions of the printer 


(300x300). 


Below is the data block returned for the ImageWriter. 

















Error Code (0 = okay) 1 word 
RangeType = 1 1 word 
X Resolution Range: 
min =0, max = 0 2 words 
Y Resolution Range: 2 words 
min = 0, max #0 
Resolution Record Count = 4 1 word 
Resolution Record #1: 2 words 
X = 72, Y = 72 
Resolution Record #2: 2 words 
X =144, Y = 144 
Resolution Record #3: 2 words 
X = 80, Y = 72 

2 words 


Resolution Record #4: 
X = 160, Y = 144 


All the resolution range values are zero, because only discrete resolutions can be 
specified for this printer. There are four resolution records giving these discrete physical 
resolutions. 


Note that GetRslData always returns the same information for a particular printer 
type—it is not dependent on what the user does or on printer configuration information. 
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The SetRsl Call 


SetRsl (iOpCode = 5) is used to specify the desired imaging resolution, after using 
GetRslData to determine a workable pair of values. Below is the format of the data 
block: 


TSetRs1Blk = RECORD {data block for SetRsl call} 
iOpCode: Integer; {input; = setRslOp} 
Error: Integer; {output} 
iReserved: Longint; {reserved for future use} 
hPrint: THPrint; {input; handle to a valid print record} 
iXRsl: Integer; {input; desired X resolution} 
iYRsl: Integer; {input; desired Y resolution} 
END ; 


hPrint should be the handle of a print record that has previously been passed to 
PrValidate. If the call executes successfully, the print record is updated with the new 
resolution; the data block comes back with 0 for the error and is otherwise unchanged. 


However, if the desired resolution is not supported, the error is set to noSuchRs1 and the 
resolution fields are set to the printer's default resolution 


Note that you can undo the effect of a previous call to SetRs1 by making another call that 
specifies an unsupported resolution (such as 0x0), forcing the default resolution. 

The DraftBits Call 

DraftBits (i0pCode = 6) is implemented on both the ImageWriter and the LaserWriter. 


(On the LaserWriter it does nothing, since the LaserWriter is always in draft mode and 
can always print bitmaps.) Below is the format of the data block: 


TDftBitsBlk = RECORD {data block for DraftBits and NoDraftBits calls} 
1OpCode: Integer; {input; = draftBitsOp or noDraftBitsOp} 
ifrror: Integer; {output} 
lReserved: LongInt; {reserved for future use} 
hPrint: THPrint; {input; handle to a valid print record} 
END; 


hPrint should be the handle of a print record that has previously been passed to 
PrValidate. 


This call forces draft-mode (i.e., immediate) printing, and will allow bitmaps to be printed 
via CopyBits calls. The virtue of this is that you avoid spooling large masses of bitmap 
data onto the disk, and you also get better performance. 

The following restrictions apply: 

e This call should be made before bringing up the print dialogs because it affects their 


appearance. On the ImageWriter, calling DraftBits disables the landscape icon in 
the Style dialog, and the Best, Faster, and Draft buttons in the Job dialog. 
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¢ lf the printer does not support draft mode, already prints bitmaps in draft mode, or 
does not print bitmaps at all, this cali does nothing. 


e Only text and bitmaps can be printed. 
¢ As in the normal draft mode, landscape format is not allowed. 


e Everything on the page must be strictly Y-sorted, i.e. no reverse paper motion 
between one string or bitmap and the next. Note that this means you can’t have two 
or more objects (text or bitmaps) side by side; the top boundary of each object must 
be no higher than the bottom of the preceding object. 


The last restriction is important. If you violate it, you will not like the results. But note that 
if you want two or more bitmaps side by side, you can combine them into one before 
calling CopyBits to print the result. Similarly, if you are just printing bitmaps you can 
rotate them yourself to achieve landscape printing. 


The NoDraftBits Call 


NoDraftBits (iO0pCode = 7) is implemented on both the ImageWriter and the 
LaserWriter. (On the LaserWriter it does nothing, since the LaserWriter is always in draft 
mode and can always print bitmaps.) The format of the data block is the same as that for 
the DraftBits Call. 


This call cancels the effect of any preceding DraftBits call. If there was no preceding 
DraftBits call, or the printer does not support draft-mode printing anyway, this call does 
nothing. 


The GetRotn Call 


GetRotn (iOpCode = 8) is implemented on the ImageWriter and LaserWriter. Here is the 
format of the data block: 


TGetRotnBlk = RECORD {data block for GetRotn call} 
iOpCode: Integer; {input; = getRotnOp} 
iError: Integer; {output } 
1Reserved: LongInt; {reserved for future use} 
hPrint: THPrint; {input; handle to a valid print record} 
fLandscape: Boolean; {output; Boolean flag} 
bXtra: SigqnedByte; {reserved} 
END ; 


hPrint should be the handle to a print record that has previously been passed to 
PrValidate. 


If landscape orientation is selected in the print record, then fLandscape Is true. 
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How To Use The PrGeneral Opcodes 

The SetRsl and DraftBits Calls may require the print code to suppress certain options 
in the Style and/or Job dialogs, therefore they should always be called before any call to 
the Style or Job dialogs. An application might use these calls as follows: 


¢ Get a new print record by calling PrintDefault, or take an existing one from a 
document and call PrValidate on it. 


| e Call GetRslData to find out what the printer is capable of, and decide what 
resolution to use. Check PrError to be sure the PrGeneral call is supported on this 
version of the print code; if the error is ResNotFound, you have older print code and 
must print accordingly. But if the PrError return is 0, proceed: | 
e Call SetRs1 with the print record and the desired resolution if you wish. 
e Call DraftBits to invoke the printing of bitmaps in draft mode if you wish. 


Note that if you call either Set Rs1 or DraftBits, you should do so before the user sees 
either of the printing dialogs. 
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#129: SysEnvirons 


Written by: Jim Friedlander May 4, 1987 
Modified by: Louella Pizzuti November 2, 1987 





This technical note describes version 1.0 of the SysEnvirons Call. Modified 
November 2 to reflect MPW 2.0 availability. 





Due to the increased complexity of the Macintosh environment, a true Environs call is 
more necessary now than ever. The following call is available in System 4.1 (and later) 
and in glue for pre-4.1 Systems, as well as for the 64K ROM and the Macintosh XL: 


FUNCTION SysEnvirons (versionRequested: Integer; VAR theWorld: 
SysEnvRec) :OSErr; 


OSTrap $A090 


AO.L (input) => pointer to SysEnvRec 
DO.Ww (input) > VersionRequested 


AO.L (output) e pointer to SysEnvRec 
DO.W (output) <— error result 


The SysEnvirons Call currently fills out the following Pascal record: 


SysEnvRec= RECORD 
environsVersion : Integer; 
machineType : Integer; 
systemVersion : Integer; 
processor : Integer; ° 
hasFPU : Boolean; 
hasColorQD : Boolean; 
keyBoardType : Integer; 
atDrvrVersNum : Integer; 
sysVRefNum : Integer; 
END; {SysEnvRec } 
Extensibility 


SysEnvirons is designed to be extensible as follows: The caller will make the call and 
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request a version number. The initial version of SysEnvirons will be version 1, with 
subsequent versions incremented by 1. Version 2 will add more fields to the record and 
so on. If a caller requests version 2 and only version 1 is available, the information for 
version 1 will be filled in, and the function result will be envSelTooBig. At this point, the 
caller can check the first field in the record (environsVersion) to see what version of 
SysEnvirons is present (i.e. how much data is returned). 


When can SysEnvirons be called? 


SysEnvirons İS written as an OS Trap, so the glue can check for the existence of the 
trap at runtime. If the call does not exist at runtime, the glue will return an error 
(envNotPresent = -5500) that indicates that the glue, not the trap, has filled in the 
information (see pp. 4-5). The current glue will fill in all version 1 fields except 
SystemVersion. 


SysEnvirons must be called after all the ToolBox inits (as well as after MPPOpen if 
AppleTalk Driver version information is desired). SysEnvirons is not intended for use 
by drivers, but can be called from DAs (it doesn’t assume an A5 world). 


Calling SysEnvirons from assembly language 
Assembly-language programmers should link with the glue and do a 
JSR SysEnvirons 
if the glue is not available, you will need to check to see if the SysEnvirons trap is 
available. From MPW Assembler you can test for the existence of the trap as shown in 


the following fragment: 


Unimpl EQU SOF ; trap number of unimplemented trap 
SysEnv EQU $90 ; trap number of SysEnvirons 


TST.W ROM85 ; are we on 64K ROMs? 
BLT.S NoSysEnv 7; never on 64K ROMs 

MOVE . W #Unimp1,D0 * get address of the unimplemented trap 
_GetTrapAddress, NEWTOOL 


MOVE .LAO,Al1 ; save off result 

MOVE . W #SysEnv, DO ; get address of SysEnvirons’ trap 

_GetTrapAddress, NEWOS 

CMPA.LAQ,Al ; compare the two addresses 

BEQ.S NoSysEnv ; if the same, SysEnvirons is unimplemented 
WeHaveSysEnv ; we’ve fallen through, we have the trap 


; call the trap 


NoSysEnv 
; we don’t have it 
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Assembly Language equates 


SysEnvirons fills in the following data: 


environsVersion EQU 0 

machineType EQU 2 

systemVersion EQU 4 

processor EQU 6 

hasFPU EQU 8 

hasColorQD EQU 9 

keyBoardType EQU $A 

atDrvrVersNum EQU $c 

sysVRefNum EQU SE 

sysEnvlSize EQU $10 ; Size of the record 


information returned by SysEnvirons 

environsVersion 

This field returns the version number of SysEnvirons so that you can check to see if the 
latest version of the call is present. The initial version of SysEnvirons will return 1 in 
this field. 

machineType 


This field returns one of the following constants: 


envMachUnknown = 0; 
env512KE = 1; 
envMacPlus = 2; 
envSE = 3; 
envMacII = 4; 


In addition to these, the glue for SysEnvirons may return one of the following: 


envMac = =l}; 
envxXL = <2; 


Because the SysEnvirons glue will return correct value for machines that won't have 
the trap (Macintosh 64K ROM and Macintosh XL), envMacUnknown means a machine 
newer than a Macintosh Il. 


systemVersion 


This integer field returns the System version number represented as two byte-long 
numbers, separated by an implied decimal point (but not a fixed point number), that is, 
System 4.1 returns $0410 or 04.10 in the field. Applications can use this for compares. 
If SysEnvirons Is called while a system earlier than System 4.1 is running, the glue will 
return a $0 (and an envNotPresent error) in this field. 
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processor 


This field returns one of the following constants: 


envCPUUnknown 
env68000 
env68010 
env68020 


- 
d 
. 
# 


+ 
f 


WNr oO 


envCPUUnknown indicates a processor newer than a 68020. 

hasFPU 

This boolean field tells whether or not a Motorola MC68881 floating point coprocessor 
unit is present. (This field does not apply to third-party memory-mapped coprocessor 
add-ons.) 

hasColorQD 


This boolean field tells whether or not Color QuickDraw is present. It does not tell 
whether or not a color screen is present, as high-level Color QuickDraw calls can do that. 


keyBoardType 


This field returns one of the following constants: 


envUnknownkKbd = 0; 
envMacKbd = 1; 
envMacAndPad = 2; 
envMacPlusKbd = 3; 
envAExtendKba = 4; 
envStandADBKbd = 5; 


A Macintosh Plus keyboard with a keypad is returned as envUnknownKbd as is an XL 
keyboard, since machineType = XL tells you all you need to know. 


Using ADB, this field returns the keyboard type of the keyboard on which a keystroke 
was last made. 


atDrvrVersNum 


This field returns the version number of AppleTalk, if it is loaded. If AppleTalk is not 
loaded, the routine that fills in this field returns a O (it does not load AppleTalk). 


sysVRefNum 

This field returns the WORefNum (or VRefNum) of the directory that contains the currently 
open System file. Note: the information returned in this field does not fall prey to the 
BootDrive bug described in Technical Note #77. 


Errors Returned 
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Errors Returned 


SysEnvirons returns the following errors: 


Error Value 
noErr 0 

envNotPresent —5500 
envBadSel ~5501 
envSelTooBig -5502 


Glue Availability 


Reason 


The trap was present, and the version requested is 
supported by the trap. 


The trap was not present, glue returns all values except 
systemVersion. You are running a system prior to 
version 4.1. 


A non-positive selector was passed to the trap (in DO) 
—no information is returned. 


The requested version was greater than the trap knows 
about. This may happen in future versions of the call, 
when, for example, a program requests version 2 
information, but the system that is running has version 1 
of SysEnvirons. The call will fill in the information that 
it knows about and return this error. The application can 
check the environsVersion field of the SysEnvRec to 
see how much information was returned. 


Glue for SysEnvirons is available in MPW 2.0 which is available through APDA. 
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#130: Clearing ioCompletion 
See also: The File Manager 


Written by: Jim Friedlander May 4, 1987 


When making synchronous calls to the File Manager, it is not necessary to clear 
ioCompletion field of the parameter block, since that is done for you. 


Some earlier technotes explicitly cleared ioCompletion, with the knowledge that this 
was unnecessary, to try to encourage developers to fill in ali fields of parameter blocks 
as indicated in Inside Macintosh. 


By the way, this is true of all parameter calls—you only have to set the fields that are 
explicitly required. 
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#131: TextEdit Bugs in System 4.1 


Written by: Chris Derossi June 1, 1987 
Modified by: Chris Derossi July 1, 1987 





There is a new TextEdit in the ROMs of the Macintosh SE and the Macintosh 
il; it is also included as patches in System 4.1 for use on 128K ROM 
Macintoshes. These routines are currently documented in the draft version 
of Inside Macintosh, Volume V (available from APDA). The new TextEdit 
contains greatly enhanced functionality, but it still has some bugs. All of the 
known bugs are listed here along with workarounds that will continue to work 
when the bugs are fixed. All of these bugs should be fixed in the next 
release of the System file. 





TEStylinsert 


TEStylinsert will modify the data referenced by the input St ScrpHand1e for its own 
use. So, if you wish to preserve this data, you should make a copy of it (with 
HandToHanda) before calling TEStyliInsert. | 


The results of calling TEStylInsert with a text length of O are unpredictable, so test 
the length of the text before you call TEStyl Insert, and don't call it if it's O. 


Calling TEStylInsert while the TextEdit record is deactivated causes unpredictable 
results, so make sure to only call TEStyl Insert when the TextEdit record is active. 


TEStylInsert doesn't always merge two adjacent runs of identical style. Although this 
doesn't really hurt anything, it can cause extra memory to be used. This simply causes 
more than one entry with the same information to be stored in the styleTab. 


TESetStyle 


TESet Style doesn’t work if the selection range is empty. This means that you cant set 
a style to be applied to the next characters typed when you have no selection (just an 
insertion point). Although this isn’t recommended if you can possibly avoid it, you can 
remember the style that the user asks for, and save it until the next keyDown. Then, call 
TESetStyle for the newly entered character(s). You will also have to be very careful to 
watch out for things like the user clicking somewhere else before typing, the user 


Technical Note #131 . page 4 of4 TextEdit Bugs in System 4.1 


pressing backspace, etc. 


When using the doFace mode with TESetStyle, the style that you pass as a 
parameter is ORed into the style of the currently selected text. If you pass the empty set 
(no styles) though, TESet Style is supposed to remove all styles from the selected text. 
But TESet Style checks an entire word instead of just the high-order byte of the 
tsFace field. The style information is contained completely in the high-order byte, and 
the low-order byte may contain garbage. 


If the low-order byte isn’t zero, TESet Style thinks that the t sFace field isn't empty, so 
it goes ahead and ORs it with the selected text’s style. Since the actual style portion of 
the tsFace field is zero, no change occurs with the text. If you want to have 
TESet Style remove all styles from the text, you can explicitly set the tsFace field to 
zero by doing something like this: 


VAR 
myStyle : TextStyle; 
anIntPtr : “Integer; 


BEGIN 
anIntPtr := @myStyle.tsFace; 
aniIntPtr* := 0; 
TESetStyle(doFace, myStyle, TRUE, textH); 


END; 


TEGetHeight 


The startLine and endLine input parameters are reversed. To make this function 
work correctly, change the declaration to be: 


FUNCTION TEGetHeight (endLine, startLine: LongInt; hTE: TEHandle): LongInt; 


Our final fix for this problem will be to reverse the parameters in the declaration instead 
of changing the actual routine. 


TEStyINew 


The line heights array does not get initialized when TESty1New is called. Because of 
this, the caret is initially drawn in a random height. This is easily solved by calling 
TECalText immediately after calling TESt y1New. Extra calls to TECalText don't hurt 
anything anyway, so this will be compatible with future Systems. 


On the Macintosh SE only, TextEdit changes a point size of 0 to 1, because 1 is the 
smallest legal point size. QuickDraw, on the other hand, treats a point size of 0 as the 
default of 12. So, before you call TESt ylNew, make sure that the current port's txSize 
field isn’t 0. You can set it yourself by calling Text Size. Be careful not to set the point 
size to 0 with TESet Style. 
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Fixed Line Heights 


The Beta draft version of Inside Macintosh Volume V states that you can set a fixed line 
height by setting the lineHeight and fontAscent fields of the TERec to positive 
values. This is supposed to override the information in the line-height table. This 
doesn't work yet, and creates improperly drawn text and weird highlighting effects. 
There is no direct workaround for this, but you can simply avoid this feature and let 
TextEdit do the line height calculation for you. 


Text Deletion 


Under certain circumstances, if you select a portion of text within a single line and 
delete it, the text doesn’t get redisplayed properly. The caret is drawn on the previous 
line, and it looks like more than just the selected text has been deleted; any editing 
action after the text deletion causes the display to correct itself and the missing 
characters to return. We currently have no workaround for this problem. 


Low Stack Crash 


A TEClick or any action causing the lineStarts array to be recalculated (insertion or 
deletion of text) could result in a system error if the available stack space is less than 
twice the length of the longest line of text in the TextEdit record. There is no good 
workaround for this. You might try making sure that you never come close to running 
out of stack space, but even that won't help with very long lines of text. 


32K of Text 


If the length of your text is exactly 32,767, a system error could occur if TECal Text is 
called to recalibrate the text. This can be avoided by limiting your text length to 32,766. 
In practice, text length should be limited to a much lower number to ensure adequate 
performance. 


TEScroll 

The bug documented in Technical Note #22 remains in the new TextEdit. TEScroll 
called with zero for both vertical and horizontal displacements causes the insertion 
point to disappear. The workaround is the same as before; check to make sure that dv 
and aH are not both zero before calling TEScroll. 

TextWidth 

On the Macintosh SE only, a patch to TextWidth dereferences the handle that is 
stored in the txFont and txFace fields of a TERec, without first checking to see if itis a 


new-style TERec. This means that for old-style TERecs, TextWidth is dereferencing 
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data this is not a valid handle. If the low-order byte of the txFace field is odd, an 
address error results. 


The txFace field is copied from the current port’s txFace field when TENew is called. 
During normal use, the low-order byte of the txFace field is zero, because InitPort 
clears it to zero, and the text style information is completely contained in the high-order 
byte. So the only way the low-order byte can become non-zero is for something other 
than the ROM to change it. 


Your code should never change the txFace field in a GrafPort directly, but should 
instead call TextFace to let QuickDraw change it for you. If you change the txFace 
field in a TERec, make sure to either set the low-order byte to zero, or just leave it alone. 


Growing TextEdit Record 


TextEdit is supposed to dynamically grow and shrink the LineStarts array in the 
TERec SO that it has one entry per line. Instead, when lines are added, TextEdit 
expands the array without first checking to see if it’s already big enough. In addition, 
TextEdit never reduces the size of this array. 


Because of this, the longer a particular TextEdit record is used, the larger it will get. This 


can be particularly nasty in programs that use a single TERec for many operations 
during the program ’s execution. 
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#132: AppleTalk Pascal Interface Update 


See also: AppleTalk Manager 
Inside AppleTalk (for ZIP information) 
Technical Note #121—Using the High-Level 
AppleTalk Routines 


Written by: Bryan Stearns July 1, 1987 





nn 


Technical Note #121 announced that we would be moving to a simplified 
AppleTalk Manager interface. That interface is available now, as part of MPW 
2.0 (as of the 2.0B1 version). This note serves as preliminary documentation 
for this interface. 





The original AppleTalk Pascal Interfaces, known as ABPasIntf, were designed to 
simplify use of AppleTalk from high-level languages. Instead, they’ve caused us a few 
compatibility problems. We’ve decided to encourage use of the same interface that 
assembly-language AppleTalk uses, a parameter-block interface in the same style as the 
low-level interfaces to the File and Device Managers. 


The original calls are still supported (and will be for a while) as an “alternate” interface, 
but we suggest that you consider moving to the new “preferred” calls. Be warned that use 
of the original calls may cause compatibility problems with future system software. Also, 
new protocols (like ASP, the AppleTalk Session Protocol) are only provided with the new 
interfaces. 


The new interface uses parameter blocks like those used by the File and Device 
Managers; you fill out the call-specific fields of the block, and a small amount of glue 
code (provided with development environments like MPW) turns the parameter block into 
a Control call to the appropriate AppleTalk driver. 


Most calls have an interface like: 

FUNCTION PSomeCall(thePBPtr: ATPPBptr; asyncFlag: BOOLEAN): OSErr; 
The glue fills in the fields csCode and ioRefNum with the appropriate value for the call 
you’re making. For specific information on filling in the parameter blocks for these calls, 
see the “Using AppleTalk From Assembly Language” section of the AppleTalk Manager 


chapter. Also, see the MPW Pascal interface file “AppleTalk.p”, as a few of the field 
names have changed. 
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Synchronous and Asynchronous calls 


You can still make calls synchronously (“do it now”) or asynchronously (“start it now, 
finish it soon”). If you choose to make a call asynchronously, be sure to provide a 
completion routine in the ioCompletion field (to be called when the call finally finishes), 
or poll the ioResult field of the parameter block (the call is done if ioResult is less 
than or equal to 0). 


You must not move or dispose of a parameter block before the call finishes; when the 
call does complete, you are responsible for throwing the parameter block away (if you 
allocated it using Memory Manager routines). 


Note that the alternate interfaces generated a network event on completion of an 
asynchronous Call; this service is not provided by the preferred interfaces, partly because 
of future compatibility problems. See Technical Note #142, “Avoid Use of Network 
Events,” for background information. 


Packed data structures 


Several of the data structures used by the new interfaces are packed; Pascal doesn’t 
dea! well with these structures. Special calls are provided for building LAP and DPP 
write-data structures, NBP names-table elements, and ATP buffer data structures. 


For example, when registering a name (using PRegisterName), you'll use a 
NamesTableEntry Structure. This structure consists of a few unpacked fields, followed 
by an entity-name: three strings (representing the object, type, and zone fields of the 
name) packed together. You can call NBPSetNTE to pack the strings into the 
NamesTableEntry structure. When you remove the name (PRemoveName), you'll use the 
entity-name by itself; you can use NBPSetEnt ity to pack it in. 


Zone Interface Protocol 
A function, Get BridgeAddress, is provided to obtain the node ID of a bridge, for use in 


ZIP transactions (zero is returned if no bridge is present on your network). You make ZIP 
calls using ATP requests, as described in the Inside AppleTalk chapter on ZIP. 
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#133: Am | Talking To A LaserShare Spooler? 


See also: PostScript Language Reference Manual, Adobe Systems, 
Inc. 
Adobe Systems Document Structuring Conventions, 
version 2 

Written by: Ginger Jernigan July 1, 1987 


When the LaserShare spooler is on an AppleTalk network it acts like a LaserWriter-type 
device, which can be chosen and communicated with much like a real LaserWriter. 
Some applications, however, must communicate with a LaserWriter directly, not a 
spooler. If this is true for your application, you can check whether you are actually talking 
to a real LaserWriter by sending to the LaserWriter the following query: 


%'PS-Adobe-1.2 Query 

Title: Query to Spooler/Non-Spooler status 
%$%?BeginSpoolerQuery 

(0) = flush 

$%?EndSpoolerQuery 1 

t tEOF 


(The query has to be sent using the Printer Access Protocol (PAP). The object code for 
PAP is available from Licensing.) lf the string returned begins with a ‘%%’ then it is a 
status string and you can ignore it and wait for another string. If the LaserWriter is 
actually a LaserShare spooler, then the string that is returned will be ‘1’. If the 
LaserWriter is a real LaserWriter then the string returned will be ‘0’. 
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#134: Hard Disk Medic & Booting Camp | 


See also: Hard Disk Users Manual 
Technical Note 154: Macintosh Plus ROMs 
Technical Note 113: Boot Blocks 
Technical Note 67: Finding the ‘Blessed Folder’ 


Written by: Bo3b Johnson July 1, 1987 


ei 


The death of a hard disk with megabytes worth of data can be exceedingly 
traumatic. This technical note will describe techniques for recovering a hard 
disk and the data that is on it. The discussion will also include some tips on 
how to avoid problems. 


You should never need this information. However, software problems can wreak havoc 
upon otherwise functional disks. When they have the equivalent of a heart attack, there 
are a number of steps that can be taken to try to recover the disk. There are occasions 
when the disk itself is not bad, and it may be possible to correct the disk without having to 
reformat the disk and restore the data from a backup. This note will describe some of the 
steps that can be used with Apple Hard Disks, but most of the information pertains to all 
hard disks. For example, the HD SC Setup program is specific to the Apple drives, but 
there is probably a similar utility for every hard disk. This is primarily a discussion of 
what to do from the user standpoint, but there are a few suggestions on ways of 
retrieving data via programmatic means. 


This discussion will focus on the SCSI disks since they are more complex in terms of the 
booting sequence. For other hard disks, like the standard HD-20, most of the information 
still applies, but the obviously SCS!-specific sequences can be ignored. For example, 
the standard HD-20 also has an installer program, although it is different than HD SC 
Setup. 


Attack of the Nasties 
There are a number of unusual conditions that a hard disk may get itself in: 
1) The data is intact, but the hard disk won't boot. 
2) The SCSI disk won't boot and only shows up after running HD SC Setup. 


3) The disk will boot but hangs part way through the boot process. 
4) There are data errors while the disk is running. 
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5) The disk is very slow returning to the Finder. 

6) The computer crashes or hangs when returning to the Finder. 
7) The disk appears in a “This disk is bad” dialog. 

8) The disk never shows up at all. 


These problems can develop from a number of sources, including system crashes, 
rebooting at bad times, power fluctuations, malicious software, old software, buggy 
software, etc. In general, these problems will be software-related, since the hardware 
itself is. very rarely defective. 


This technical note will discuss: 


1) The normal stages in the booting process. 

2) Results of errors during the various stages in the booting process. 

3) A step-by-step procedure to follow in order to maximize your chances of recovering 
the disk and the data. 


A Boot to the Head 


This discussion will detail a normal boot process of a Macintosh with a single hard disk 
attached. For clarity, this section will deliberately ignore potential problems and the 
complexities involved in different configurations. The following sections will detail some 
errors that may occur, and give more information in terms of what the ROM will do to boot 
the system. A SCSI disk can be thought of in the following fashion: 


dia 


The Physical Disk 







a tian Macintosh Volume 


Block Block Block Block|Block 
N+1 [N+2 | N+3 N+M| X 


EEM the — of Disk: 
SCSI Driver Block N+2: Macintosh Other Operating Systems 
Master Directory Block or other partitions 


Block N+1: 2nd Macintosh boot block. 


Block N: First block of HFS volume Last block on Volume: 
Macintosh bodtlock. Copy of Master Directory 
Block 


Block 0: SCSI partition informatia 


The important thing to note from this diagram is that the Macintosh volume is a subset of 
the entire SCSI Disk. There can be more than one Macintosh volume on a given disk, or 
even other volumes that are not Macintosh volumes. 
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1) Check the SCSI port: 


Immediately after the RAM check, the system looks at the SCSI port to see if there are 
any drives connected. If a SCSI drive is found the system reads the SCSI partition 
information in block 0. This block is specific to SCSI drives and is always found at block 
0 of the disk. The SCSI Manager then reads in the SCSI driver from the disk. Once the 
driver is loaded into memory, the system will use the driver to read and write blocks from 
the disk, instead of the ROM boot code. The driver reads and writes blocks relative to the 
beginning of the Macintosh volume on the SCSI drive, which can start anywhere on the 
physical disk. 


2) Decide which disk is to be the startup disk: 


The Macintosh then looks at the floppy disks to see if there is a disk that it should try to 
use. If so, it will always boot from the floppy. If there are no floppy disks, the startup hard 
disk is chosen. The Macintosh boot blocks are read off of the chosen disk to determine if 
the volume is bootable. The two Macintosh boot blocks (same boot blocks as those 
found on floppies) are read using the SCSI Driver. The Macintosh boot blocks are found 
as the first two blocks on the Macintosh volume, but are much higher in terms of where 
they are found on the disk itself. See the figure for the difference between the 
Macintosh volume and the SCSI disk. The driver cannot normally read the SCSI partition 
information, or any blocks outside of the Macintosh volume. l 


3) Execute the Macintosh boot blocks: 


The boot blocks are composed of strings and parameters which determine various 
system functions, and code that finishes the job of booting the system. 


The hard disk is mounted as a volume, using the PBMount Vol call. The volume has the 
two Macintosh boot blocks, as well as the volume header. The PBMountVo1 will use the 
driver to read the volume header and other information from the disk. Once the volume 
is mounted, there are only volume reads and writes, and the driver is responsible for the 
actual SCSI disk reads. 


The System file is opened on the volume. The patch code for the current ROM is read 
into the system, including the patches to the SCSI Manager. 


The Finder is launched. 
4) The Finder uses the Desktop file on the volume to draw the desktop. 


The Icons that make up the desktop representation of the Macintosh volume are stored in 
the Desktop file. The Desktop file is invisible and used only by the Finder. 


That is a rather simplistic view of the boot process. There are a number of complications 
that arise due to the wild variety of devices that can be attached to a Macintosh. The full 
boot process is essentially a series of special cases, leading to the final booted System 
at the Finder’s desktop (or in the startup application). The following section will go into 
painstaking detail in order to give you enough information to determine what step in the 
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boot process failed. 
Tough Boots 


To further explain the boot process: 


1) Check the SCS! port: 
a) Before starting the boot process, the screen will be filled with the grey desktop 


pattern. 


b) Before the Macintosh will check for any SCSI devices, it will first reset the SCS! 


c) 


d) 


e) 


bus using a SCSIReset. This is to make sure the bus was not left in a bad state. 
The Macintosh will then start a cycle through all 7 SCSI IDs (from 6..0) to see 
which disks are connected, and keeps a table of all disks that are connected. 

For each disk that is connected to the Macintosh, the ROM boot code will use the 
SCSI Manager to read in the SCSI partition information to find where the driver is 
located on the disk. The signature of the SCSI partition information is also 
checked to be sure that the device is valid. 

The SCSI Manager will then be used to read the driver into memory. Once the 
driver is loaded for a given disk, the driver is called to install itself. The driver will 
usually post a Disk Inserted event to have its volume mounted by the Finder. 

Steps d and e are repeated for each disk connected. At this point, there may be a 
number of drivers in memory, but there are no volumes, since none have been 
mounted yet. Generally there is one driver per disk, but some drivers can handle 
more than one disk at a time. 


2) Decide which disk is to be the startup disk: 


a) 


b 


T” 


d 


“eee” 


e) 


The next stage is to determine which volume will become the startup disk. If there 
is a floppy available it will always be the startup disk. During this process the disk 
chosen as the startup disk is not known to be valid. The System file and boot 
blocks are checked later. 

The standard HD-20 is connected to the system in a fashion that is very similar to a 
floppy, so if a bootable HD-20 is connected it will be the startup disk. 

There is no search for floppy devices like there is for the SCSI disks since the 
driver for the floppies will post a Disk Inserted event when it detects a floppy in the 
drive. The first floppy device that is found will be used as the startup disk. if there 
are multiple floppy devices, the others will be mounted by the Finder, not during 
boot time. The SCSI devices that are online are not explicitly mounted at this time, 
either. There is a pending Disk Inserted event for each of the disks that will be 
handied by the Finder. 

At boot time, there is only one volume that is mounted (during execution of the 
Macintosh boot blocks). The others will be mounted when their Disk Inserted event 
is processed at a GetNextEvent Call. 

On the new Control Panel there is a Control Device (cdev) called the Startup 
Device. This Startup Device cdev allows the user to choose which device the 
system should try to boot from first. This can only be used on the Macintosh Il and 
SE. The drive number, driver reference number, and driver OS type are stored in 
parameter RAM to allow a chosen device to be the boot disk. The floppy drives will 
still have precedence over the SCSI devices. The standard HD-20 can be chosen 
as the Startup Device as well, since it uses a different driver reference number. If 
the drive number that is stored as the Startup Device is invalid, or had a read/wnte 
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error, then another disk in the chain will be chosen as the next bootable candidate. 
Remember that there is only one boot/startup/system disk, and it is the only one 
that is explicitly mounted at boot time. All other devices in the system will be 
handled once the system is booted. 


3) Execute the Macintosh boot blocks: 

a) Once the Startup Disk has been chosen (whether floppy, SCSI or other disk) then 
it is time to read the Macintosh boot blocks off of blocks 0 and 1 of the volume. 
Those boot blocks determine various parameters in the system, such as whether a 
Macsbug-like debugger will be loaded, the name of the startup program (not 
always the Finder), how big to make the event queue, how big to make the system 
heap, and so on. They also contain a signature identifying them as Macintosh boot 
blocks, and a version number to differentiate between different boot blocks. 

b) After the boot blocks are read and the signature verified, the smiling Macintosh is 
displayed on the screen. The smiling Macintosh basically means that valid 
Macintosh boot blocks were found. 

c) On 64K ROMs the boot blocks are executed by jumping to the code that follows the 
header information in boot block 0. On the newer Macintoshes the boot block 
version number is checked, and if it is ‘old’ the boot blocks will be skipped. The 
same code that would have been found in the boot blocks is found in the ROM 
itself. Regardless of which kind of Macintosh it is, the following steps apply. For 
the newer Macintoshes the boot blocks are usually used only for the parameters 
stored in the header. 

d) Do the PBMountVol on the chosen startup volume. If PBMountVol fails, the 
process starts over at the point where a startup disk is being chosen (step 2 
above). The failing volume is marked out of the list of candidates so that it won't be 
used again. 

Find the System file and create a Working Directory, if needed, for the System 

folder. This is only done for HFS volumes of course, and the directory ID is set to 

the blessed folder. The blessed folder is saved in the volume header as part of the 

FinderiInfo field. See Technical Note #67 for more information on the blessed 

folder. If the directory ID is wrong, the System file won't be found, causing it to start 

over again (at step 2 above). If the Working Directory was created successfully, 
that WoORefNum is set as the default volume with Set Vol. 

f) The System file is opened with openResFile. If the file could not be opened, the 
process starts over again at the point where a suitable boot device is being chosen 
(step 2 again). 

g) The Startup Screen is loaded and displayed. If there was no Startup Screen, the 
normal “Welcome to Macintosh” message will be displayed. The Startup Screen 
or “Welcome...” means that the System file was found and opened successfully. 
On the Macintosh Plus and 64K ROM machines, the Startup Screen is displayed 
before the System file is opened. (reverse steps f and g) 

h) The debugger and disassembler are installed if found. The names of the 
debugger and disassembler are found in the header of the boot blocks and are 
usually Macsbug and Disassembler respectively. 

i) The data fork of the System file is opened and executed. The data fork contains 
code to read in the PTCH resources which patch the ROM. 

j) The INITs that are in the System file are executed. The last INIT is INIT 31 which 
then looks in the System Folder for other INITs to be executed. 


© 
Sane” 
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k) The file specified by the boot blocks as the startup application (Set Startup at the 
Finder) is found on the volume, using another field in the FinderiInfo field of the 
volume header in order to get the Directory ID. If the file exists, it is launched. If 
not, the Finder is launched. If the Finder is not found, SysError is called with error 
code of 41 which is the “Can't launch Finder” alert. 


4) The Finder uses the Desktop file on the volume to draw the desktop. 


if the startup application was the Finder, it opens the Desktop file on the startup volume 
in order to draw the desktop. When it finishes with the startup volume, it calls 
GetNextEvent. If there are any pending Disk Inserted events, the volume specified is 
mounted (by the ROM) and the result passed to the Finder. If PBMount vol failed for any 
reason, the bad result will be passed to the Finder. At that point the Finder would put up 
the “This disk is damaged” alert and ask if the volume should be initialized or ejected. If 
ejected, the driver for that volume still exists, but the volume is unmounted. For each 
volume that the Finder sees, it opens the Desktop file on the volume to get the 
information that it needs to build the desktop. If the Desktop file was not found on a 
volume, it is created. If there are any errors while creating or using the Desktop file, the 
Finder will display the “This disk needs minor repairs” message. If the OK button is 
clicked, the Finder will delete the old file and create a new one. If that fails, the volume is 
unmounted and deemed unusable by the Finder. This happens if the disk is locked, or 
too full to add a Desktop file. If that was the startup volume, the computer is rebooted 
since it was forced to unmount the startup volume, and cannot run if there is no startup 
volume. 


If you follow the previous sequence closely, you can predict what errors are causing a 
given end result. For example, if you have the effect where the smiley Macintosh 
appears, but immediately goes away and the disk does not boot, you can look through 
the sequence to see what might be going wrong. In this case, we know that the boot 
blocks were found on our startup volume, since the smiley Macintosh was displayed. We 
know that the System file was not found, or failed to open, since we never got the 
Welcome message. This usually calls for throwing away all of the System Folders on the 
volume, and starting again with a new System Folder to fix the problem. If there is more 
than one System Folder on a volume it is possible to confuse the system. 


Other tidbits of information that may be useful (in no particular order) some which will be 

mentioned in the step-by-step operation below: 

1) The SCSI cables have a lot of wires in them, and are rather bulky because of it. Itis 
best to avoid bending the cables too much or too often, since the wires inside will 
break if overstressed. Don't put wild kinks in the cable in order to make it fit behind 
the Macintosh. 

2) If there is no default volume stored in the parameter RAM with the Startup Device 
cdev, then the first drive that is in the drive queue will be the Startup Device. Since 
SCSI drives are added in highest ID order, that means the larger SCSI IDs will have 
a higher ‘priority’. Macintosh IIs will default to the internal hard disk. 

3) If the parameter RAM is trashed for some reason, the boot process can fail since a 
driver OS type is stored as well. If the OS type is wrong, the ROM will skip that 
driver, making the disk unbootable. On the Macintosh II/SE, the battery is no longer 
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removable to fix parameter RAM problems. To correct this problem the Control 
Panel now has a feature that will allow you to clear parameter RAM. Holding down 
the Option-Command-Shift keys while opening the Control Panel will reset 
parameter RAM, forcing it to be rebuilt and therefore losing all of your settings, but 
possibly fixing some booting problems. 

4) The Macintosh II and SE both have a new feature that will allow you to skip having 
the any hard disk mounted. Holding down the Option-Command- Shift-Delete 
combination will have the startup code skip the SCSI hard disks on the system. This 
can be useful if you are booting an old System file that does not understand HFS 
disks (like System 2.0/Finder 4.1), and want to avoid having your hard disks on line 
while you do something shaky. With external hard disks it is easier to just turn them 
off, but with internal disks it is not so easy. 

5) Since the parameter RAM can be trashed in a manner that makes it impossible to 
boot a volume (looking for the wrong OS type), a new feature was added to the HD 
SC Setup program to have it fix this problem as well. If you have version 1.3 or 
greater, the parameter RAM bytes that determine booting will be reset to fix some 
boot problems that occur. The parameter RAM is fixed when the Update button is 
clicked. This does not invalidate the rest of parameter RAM, it merely fixes the bytes 
used for the Startup Device. 

6) When the Finder copies a new System Folder onto a disk that does not already 
have a System Folder, that new folder will become the blessed folder. Its Directory 
ID will be saved in the volume header. In addition, the Macintosh boot blocks will be 
copied from the current startup device to the destination device. This is the best way 
to fix System Folder or Macintosh boot block problems. in order for the blessed 
folder to be set correctly, all System Folders on the volume should be deleted before 
copying the new folder there. 

7) Ifthe Desktop file is damaged for whatever reason, it can be deleted with a number 
of programs. This will force the Finder to rebuild it from scratch. You can also have 
the Finder rebuild the Desktop file by holding down the Option-Command keys 
when the Finder is launched. When the Desktop file is rebuilt you lose the Finder 
Comments in the Get Info boxes. 

8) Onthe 64K ROMs, whenever something goes wrong during booting (like System file 
not found, bad boot blocks, and so on) the Sad Mac Icon is displayed. Starting with 
the 128K ROMs, whenever something goes wrong the ROM jumps back to the start 
to try to find another disk to use. | 


Bo3b’s Boot Repair 


This section will detail step-by-step processes that can be used to fix some common 
booting and volume problems. It is not intended to cover every possible case. The 
purpose of the preceding sections was to give you the information that will allow you to 
figure out what might be going wrong. 


For most hard disk users, it is not sufficient to merely have the device running. It is 
generally a good idea to make the system as robust as possible in order to avoid some 
of the problems that might cause a volume to become wholly unreadable. The ultimate 
fix is to reinitialize the volume from scratch and rebuild the volume with the Finder or a 
restore operation that uses the File Manager. This is guaranteed to fix anything except 
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hardware problems, and will give you the most solid system. If your system is acting 
funny, you can try the following sequence that is the next best thing to initializing the disk. 
This sequence will not make you rebuild the disk, but can be fooled by some disk 
problems. If everything passes, then the disk is in good shape; maybe not perfect, but 
good. 


1) Power down the entire system, including the hard disk that is suspect. 

2) Run the HD SC Setup program (or equivalent) and Update the drivers on the disk. 
For HD SC, this also fixes the parameter RAM. For non-Apple drives, the parameter 

- RAM can be reset with the Control Panel. 

3) Run the Test Disk option in HD SC Setup (or equivalent). If the test fails, reinitialize 
the volume, since it is not worth risking future problems. 

4) Run the Disk First Aid utility. This utility will work on all HFS volumes. Have it check 
the volume for consistency. If it reports any errors, you can have it fix the problem, but 
the safest tack is to reinitialize. There are some problems that Disk First Aid won't 
catch. If Disk First Aid says the volume cannot be verified, it is time to reinitialize. 

5) Rebuild the Desktop file by holding down Option-Command when returning to the 
Finder. 


If you can successfully perform all of these steps, the volume will be as solid as it can get 
without reinitializing the disk. If things are still funny, it is time to take the last recourse, 
reinitialize. 


Based on the previous sections, it is now time to go through all of the Nasties to give a 
step-by-step sequence for fixing these problems. 


1) The data is intact, but the hard disk won’t boot. 


This is for the case where the volume won't boot, but if the computer is booted with a 
floppy disk the volume shows up at the desktop and can run normally. For this case, we 
know that the driver is being loaded and working, since the volume shows up at the 
desktop. The volume is also mountable, since it shows up with no problem. This implies 
that the Macintosh boot blocks are wrong, or the blessed folder is wrong. Clues such as 
the smiling Macintosh can tell you how far the process got before it failed. For example, 
if the smiling Macintosh never appeared, we know that Macintosh boot blocks were not 
read successfully. When the volume is fixed and bootable, it would be a good idea to go 
through the steps above to make the volume as solid as possible. 

The sequence to follow: 

a) Power down the entire computer, including the hard disk. Try to boot again. If it 
works, you are done. 

b) Use the Control Panel’s Startup Device to set the hard disk as the Startup Device. 
This will also reset some of the bytes in parameter RAM. Try rebooting to see if it 
has fixed the problem. 

c) Run HD SC Setup (or equivalent) and perform the Update Drivers procedure. In 
the HD SC Setup case this will also rewrite the parameter RAM. If you are not 
using HD SC Setup, blast the parameter RAM with the Control Panel. Try 
rebooting. 

d) Delete all System Folders from the hard disk. Using Find File or something 
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similar, be sure that there are no stray copies of the System or Finder buried in 
some iong lost folder. Copy a new System Folder to the volume, using the Finder. 
This process will fix bad boot blocks, as well as a bad blessed folder. Try 
rebooting. 

e) If it still won't boot, there is something very strange happening. Whenever things 
get too weird it is usually time to start over: reinitialize. 


2) The disk won't boot and only shows up after running HD SC Setup. 


The disk does not even show up at the Finder when the system ts booted with a floppy. 
After running the HD SC Setup (or equivalent) the volume will appear on the desktop 
and be usable. The HD SC Setup and most similar utilities will do an explicit 
PBMountVol of the volume in order to make the volume usable. Since the volume does 
not show up at the Finder at first, this implies that the driver itself is not getting loaded or 
is working improperly, since there was no Disk Inserted Event for the Finder to use. 

The sequence: 

a) Power down completely, including the hard disk. 

b) Run HD SC Setup (or equivalent) and Update the Drivers. For non-Apple drives, 
update the drivers on the volume (this rewrites the SCSI partition information as 
well) using the utility that came with the disk. Reset the parameter RAM using the 
Contro! Panel. 

c) If it still cannot be booted or does not show up at the Finder after booting with a 
floppy, the volume is too weird and should be reinitialized. 


3) The disk will boot but hangs part way through the boot process. 


This is when you can see the volume is being accessed by the run light (LED) on the 
front panel, and the booting seems to work but never makes it to the Finder. This implies 
that all is well until the System tries to actually launch the Finder or Startup Application. 
It could also be that the System file is causing something to hang. 
The sequence: 
a) Power down completely. 
b) Boot with a floppy so that the floppy is the startup disk and the volume in question 
can be seen at the Finder. 
c) Delete all System Folders on the hard disk. Put a new System Folder on the disk. 
This will presumably fix a corrupted System file. 
d) If still funky, show the disk who’s boss. 


4) There are data errors while the disk is running. 


This case usually evidences itself by messages at the Finder when trying to copy files. 
Messages like “The file ^0 could not be read and was skipped” usually mean that the 
drive is passing back 1/O errors. This usually means that there is a hardware failure, but 
it can occasionally be caused by bad sectors on the disk itself. If the sectors are actually 
bad, it is generally necessary to reinitialize the volume. 

The sequence: 

a) Power down completely. Reboot and see if the same file gives the same error. 

b) Run the HD SC Setup (or utility that came with your drive) and perform the Test 

operation. This will fail if there are bad blocks on the device. If there are bad 
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blocks, it is necessary to reinitialize the volume. 

c) Check the SCSI terminators to be sure they are plugged in correctly. There can be 
no more than two terminators on the bus. If you have more than one SCSI drive 
you must have two terminators. If you only have one drive, you should use a single 
terminator. If you have more than one drive, the two terminators should be on 
opposite ends of the chain. The idea is to terminate both ends of this wire that 
goes through all of the devices. If you have a Macintosh IlI or SE with an interna! 
drive, that drive will already have one terminator inside the Macintosh at the front of 
the cable. 

d) Make sure the SCSI cables you are using are OK, by swapping them with known 
good ones. If the problem disappears, the cable is suspect. 

e) Swap the terminators in use with known good ones to be sure they are OK. 

f) Try the drive and cable on a different Macintosh to be sure the Macintosh is OK. 


5) The disk is very slow returning to the Finder. 


If the computer has gotten slower with age, it is probably due to a problem with the 
Desktop file. If a volume has been used for a long time, the Desktop file can grow to be 
very large (Hundreds of K). Reading and using a file that big can slow down the Finder 
when it is drawing the desktop. If you have a large number of files in the root directory, 
this will also slow the computer down. A large number (500-1000) of files in a given 
folder can cause performance problems as well. If a volume has been used for a long 
time, it can also have become fragmented. 

The sequence: 

a) Rebuild the Desktop file and see if it gets faster. 

b) Look for large numbers of files in a given directory and break them up into other 
folders if needed. 

c) Run Disk First Aid to be sure the volume is not damaged. 

d) Reinitialize the volume and restore the data using File Manager calls to fix a 
fragmentation problem. Using the Finder, or a backup program that reads and 
writes files is a way to use only File Manager calls. You cannot fix a fragmentation 
problem by doing an image backup and restore. 


6) The computer crashes or hangs when returning to the Finder. 


This can happen if the Desktop file becomes corrupted. There are occasions when this 
can happen if the HFS structures on the volume are damaged. 

The sequence: 

a) Rebuild the Desktop file. 

b) Run Disk First Aid to be sure the volume is not damaged; a boot floppy with the Set 
Startup set to Disk First Aid can allow you to test a volume that cannot be displayed 
at the Finder. 

c) The path of ultimate recourse if nothing else seems wrong with the volume. 


7) The disk appears in a “This disk is bad” dialog. 
This is the worst of the possible errors that generally happen to hard disks. If the 


message is “This disk is bad” or “This is not a Macintosh disk”, the HFS structures on the 
volume have been damaged. In particular, the Master Directory block on the volume has 
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been damaged. The driver and SCSI partition information are probably OK, since this 
dialog shows up when the Finder tries to mount a damaged volume. This means that the 
PBMount Vol Call failed. Don’t click the Initialize button unless you are sure you want the 
volume to be erased. In these cases, it is nearly always better to just reinitialize the 
volume after you have saved whatever information you can. 

The sequence: 

a) Power down completely. Occasionally the controller in the hard disk itself can 


b) 


c) 


d 


e 


Te 


Sn 


crash. 

Run Disk First Aid. For these cases, it is usually necessary to create a boot floppy 
with Set Startup set to Disk First Aid. When the floppy is booted, Disk First Aid will 
be run before the Disk Inserted events are processed. When Disk First Aid sees 
the Disk Inserted event it will check the result from the PBMountVol and still allow 
you to test the volume, even if it can’t be mounted. 

If Disk First Aid cannot repair the disk, it might be worth writing a simple program to 
call the driver to read and write blocks. There is a copy of the Master Directory 
Block on the end of the volume, and the volume can sometimes be fixed by 
copying that block over a damaged block in sector 2. You can write a program that 
will find out how big the volume is by looking in the Drive Queue Element for the 
volume, reading the block that is one sector from the end (N-1), and writing that 
copy over sector 2. At this point, the volume is probably inconsistent, but it may 
allow you to use it long enough to get information off of it. It is sometimes possible 
to have Disk First Aid repair the volume at this point as well. Copying the sectors 
can also be done with sector edit utilities, if you can get them to recognize the 
volume at all. 

If making a new copy of sector 2 does not work, but the driver is still being loaded 
at boot time, it is possible to write a program that will read sectors from the disk 
looking for information that you might need. You can have a reader program go 
through blocks looking for a specific pattern, like a known file name. This is usually 
done in desperation, but sometimes there is no other choice. If the data desired 
can be found in some form, it can sometimes be massaged back to a useful form 
much easier than recreating it. 

Sometimes the volume will be so badly damaged that the SCSI partition 
information is also damaged and cannot be fixed with the Update in the hard disk 
utility. In this case, it is usually still possible to perform direct SCSI reads, without 
going through the driver. Using the driver is preferable, since it knows how to talk 
to the drive better than you would, but sometimes the driver is not available. Using 
direct SCSI reads should be a last ditch effort since the SCSI Manager can be very 
challenging to use. This should only be used if there is irreplaceable data on the 
volume that cannot be read by any other means. 

Even if the volume is recovered, it still should be reinitialized (after the data is 
recovered) to be sure that any hidden damage is repaired. 


8) The disk never shows up at all. 


The disk appears to be missing. The volume does not show up at the Finder, and does 
not show up in HD SC Setup. At boot time the access light (LED) does not flash. This is 
usually a hardware problem as well. The drive is not responding to SCSI requests at all, 
so the system cannot tell a drive is attached. 

The sequence: 
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a) Power down the system, including the hard disk. 

b) Make sure that the SCSI ID on the drive does not conflict with any other in the 
system, including the Macintosh, which is ID 7. (If you have an internal hard drive, 
it should be ID 0.) 

c) Check the SCSI terminators to be sure they are plugged in correctly. There can be 
no more than two terminators on the bus. If you have more than one SCSI drive 
you must have two terminators. If you only have one drive, you should use a single 
terminator. If you have more than one drive, the two terminators should be on 
opposite ends of the chain. The idea is to terminate both ends of this wire that 
goes through all of the devices. If you have a Macintosh Il or SE with an internal 
drive, that drive will already have one terminator inside the Macintosh at the front of 
the cable. 

d) Make sure the SCSI cables you are using are OK, by swapping them with known 
good ones. 

e) Swap the terminators in use with known good ones to be sure they are OK. 

f) Try the drive and cable on a different Macintosh to be sure the Macintosh is OK. 


These boots are made for wokking 


Remember, the goal here is to make the system be as stable as possible. If things are 
acting strange, it doesn’t hurt to go through the entire process of testing the drive. The 
test procedure takes a little time but is non-destructive for the data that is there. If 
something catastrophic has happened to the disk, it is better to spend some time backing 
up the data, initializing the volume, and restoring the data than it is to lose some work 
later on due to some other permutation of the same problem. Unless you are sure that 
the volume is in an undamaged state, you are better off using a file-by-file backup 
operation than an image backup, since the image backup will copy any damage as well 
as the data. 


lf there are situations that you run into that are not covered by this technical note, please 
let us know so that they can added. 


If this technical note helps even one person save some data that would otherwise be 
lost, it will have been worthwhile. Hope it helps. 
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Macintosh Technical Notes Cy 


#135: Getting through CUSToms 


See also: Technical Note #88—Signals 
Technical Note #110—MPW: Writing Standalone Code in Pascal 


Written by: Rick Blair July 1, 1987 


This technical note provides a way for developers to allow sophisticated 
users to add code to an off-the-shelf application. Using this scheme, the user 
can easily install the code module; the application has to know how to call it 
and, optionally, be able to respond to a set of predefined calls from the 
custom package. 


Note 


The following code makes heavy use of features of the Macintosh Programmer's 
Workshop. It also assumes a basic familiarity with the standard Sample program 
included with MPW. The Pascal code (which is here only as an example implementation 
of the mechanism) is presented as only those sections which differ from Sample.p. The 
assembly language code also includes MPW-only features, such as record templates. 
Some of these are explained in Technical Note #88, “Signals.” 


In addition, since the order in which parameters to various routines are passed is 
critical, special care will have to be taken in writing interfaces for use with C. It is 
probably best to declare them as Pascal in the C source. 


Concepts 


Basically, we create a code resource of type CUST with an entry point at the beginning 
which takes several parameters on the stack; this code is reached via a dispatching 
routine which is written in assembly language. 


The data passed on the stack to this dispatcher includes: 

e aselector (to specify the operation desired) 

¢ the address of a section of application globals (for communication back and forth 
between the application and the module when the stack parameters are insufficient) 

e ahandle which references the custom code resource on the stack. 
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Other parameters may be added (as long as they are pushed on the stack before the 
required ones) if desired. Since these extra parameters would always have to be 
included in any calls to a given package, it might be more convenient to use the 
application global space area which is accessed through the appaddr parameter. 


Template 


Your application must contain the following global data and procedure declarations to 
support this model: 


VAR 
custhandle: Handle; 


{the following globals constitute the data known to the custom code} 
appdispatch: ProcPtr; {address of dispatch routine custom code can call} 
{examples of further application globals for the custom package: } 

(* 

paramptr: Ptr; {general pointer used as param. to appdispatch code} 
paramwordl: INTEGER; 

paramword2: INTEGER; 

CUSTerr: INTEGER; 

*) 

{any other globals the module should get at} 


{the two assembly language glue routines which are linked into the 
application} 

PROCEDURE CustomInit (resID: INTEGER; VAR custhandle: Handle); 
EXTERNAL; {the routine used to set up the custhandle resource handle} 


PROCEDURE CustomCall({application & package-specific paramters} 
selector: INTEGER; appaddr: UNIV Ptr; ourhandle: Handle); 
EXTERNAL; {this is the code dispatcher} 


{this is called by the custom package to perform a service which is more 
easily provided by the application; since we pass a pointer to it to the 
package, CustDispatch must be at the outermost nesting level in the main 
segment } 

PROCEDURE CustDispatch(selector: INTEGER) ; 


BEGIN 
CASE selector OF 
{. 
s} 
END; {CASE} 
END; {CustDispatch} 
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{your initialization code should contain the following: } 


{Custom package initialization stuff} 
appdispatch := @CustDispatch; {put pointer where the package can see it} 
CustomiInit (69, custhandle) ; {our CUST resource has ID = 69} 


{then whenever you want to invoke the package you use CustomCall) 


You must also assemble Custominit and CustomCall and link them with into your 
application. The custom package itself can be written in any language which can 
produce stand-alone code. See Technical Note #110 for how to write stand-alone code 
in MPW Pascal. 


The example 


CustomCall is only referenced once in this example. When a variety of unrelated 
functions are provided, however, it is more convenient to provide a separate interfacing 
procedure to invoke each one and have them make their own CustomCall1 Calls. 


Note that this example is somewhat contrived; you probably wouldn't “externalize” the 
code for finding a word or sequence of characters like this. This is an idealized situation. 
More realistic uses would be: to add-on special routines to a database to perform 
custom calculations or the like; allow for localization when code is required (and hooks 
aren't already provided); let documents carry around code which may vary among 
software versions, etc. so that older documents would be able to work alongside the 
new ones, etc. 


What it does 


We simply add a new menu to the sample program which allows Find by characters or 
word. We just pass the menu item to the package and let it do the finding; it then calls 
back to the application dispatch routine to highlight text or display the “not found” 
message. 


The Pascal source for the example application appears first: 


{$R-} 
{$D+} 
PROGRAM P; 


USES 

{SLOAD ::PInterfaces:most.dump} 

Memt ypes, Quickdraw, OSIntf,ToolIntf,PackIntf {,MacPrint) 
{$LOAD} 

, {$U ErrSignal.p} ErrSignal; 


CONST 


appleID = 128; {resource IDs/menu IDs for Apple, File and Edit menus} 
fileID = 129; 
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editID = 130; 
findID = 131; 


appleM = 1; {index for each menu in myMenus (array of menu handles) } 
fileM = 2; 
editM = 3; 
findM = 4; 


menuCount = 4; {total number of menus} 
windowID = 128; {resource ID for application’s window} 


undoCommand = 1; {menu item numbers identifying commands in Edit menu} 
cutCommand = 3; 

copyCommand = 4; 

pasteCommand = 5; 

clearCommand = 6; 


findcharsCommand = 1; {menu items for Custom menu} 
findwordCommand = 2; 


aboutMeCommand = 1; {menu item in apple menu for About sample item} 


aboutMeDLOG = 128; 
findDLOG = 129; 
infoDLOG = 130; 


{application dispatching code selectors} 
hilightSel = 0; 
notifySel = 1; 


VAR 


errCode: INTEGER; 
dlogString: Str255; 
custhandle: Handle; 


{here is the area known to the custom code} 

appdispatch: ProcPtr; {address of dispatch routine custom code can call) 
{examples of further application globals for the custom package] 
paramptr: Ptr; {general pointer used as param. to appdispatch code} 
paramwordl: INTEGER; 

paramword2: INTEGER; 

{any other globals the module should get at} 


PROCEDURE CustomInit (resID: INTEGER; VAR custhandle: Handle); 
EXTERNAL; {the routine used to set up the custhandle resource handle) 


PROCEDURE CustomCall(text: Ptr; count: INTEGER; findstr: StringPtr; 


selector: INTEGER; appaddr: UNIV Ptr; ourhandle: Handle); 
EXTERNAL; {this is the code dispatcher} 


{this will do the “about” dialog and the info dialog requested by the 
custom pack. } 
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PROCEDURE ShowADialog(meDlog: INTEGER); 


CONST 
okButton = 1; 
authoriItem = 2; 
languagelItem = 
infoItem = 2; 


3 


VAR 
itemHit,itemType: INTEGER; 
itemHdl: Handle; 
itemRect: Rect; 
theDialog: DialogPtr; 


BEGIN 
theDialog := GetNewDialog(meDlog,NIL,WindowPtr( - 1)); 


CASE meDlog OF 
aboutMeDLOG: BEGIN 
GetDitem(theDialog, authorItem, itemType, itemHdl, itemRect) ; 


SetIText (itemHdl, 'Ming The Vaseless'); 
GetDitem(theDialog, languageItem, itemType, itemHdl, itemRect) ; 
SetIText (itemHdl, 'Pascal et al'); 

END; 


infoDLOG: BEGIN {display the message requested by the custom 
package} | 
GetDitem(theDialog, infoItem, itemType, itemHdl, itemRect) ; 
SetIText (itemHdl, StringPtr (paramptr) “*); 
END; 
END; {CASE} 


REPEAT 
ModalDialog (NIL, itemHit) 
UNTIL (itemHit = okButton); 


CloseDialog(theDialog) ; 
END; {of ShowADialog)} 


{this will put up the Find dialog to allow the user to type in the 


characters to search for} 
FUNCTION DoCustomDialog: BOOLEAN; 


CONST 
okButton = l; 
cancelButton = 2; 
fixedItem = 3; 
editItem = 4; 


VAR 
itemHit,itemType: INTEGER; 


itemHGl: Handle; 
itemRect: Rect; 
theDialog: DialogPtr; 


BEGIN 
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theDialog := GetNewDialog(findDLOG, NIL, WindowPtr( - 1)); 
GetDitem(theDialog, editItem, itemType, itemHdl, itemRect) ; 
Set IText (itemHdl, dlogString) ; 

TESet Select (0,MAXINT, DialogPeek (theDialog) *.textH) ; 


REPEAT 

ModalDialog({NIL, itemHit) 
UNTIL (itemHit IN [okButton,cancelButton]); 
Get IText (itemHdl, dlogString) ; 
DoCustomDialog := itemHit = okButton; 


CloseDialog(theDialog) ; 
END; {of DoCustomDialog} 


PROCEDURE DoCommand(mResult: LONGINT) ; 


(* partial procedure fragment *) 
{here is one of the case sections for the DoCommand procedure} 


findID: 
IF DoCustomDialog THEN 
BEGIN 
MoveHBi (Handle (textH)); {stop it from fragmenting the heap} 
WITH textH** DO BEGIN 
HLock(hText); {since we don’t know what the package might 
be up to} 
{now call the package to find characters or words} 
CustomCall (POINTER (ORD (hText*) + selEnd), 
teLength - selEnd, @dlogString, theItem, @appdispatch, 
custhandle}) ; 
HUnLock (textH** .nText); 
END; {WITH} 
END; 


END; {OF menu CASE} {to indicate completion of command, } 
HiliteMenu (0); {call Menu Manager to unhighlight } 
{menu title (highlighted by } 
{MenuSelect) } 
END; {OF DoCommand) 


{this is called by the custom package to set the new selection or display a 
message; it must be in CODE 1 at the outermost lexical level) 
PROCEDURE CustDispatch(selector: INTEGER) ; 


BEGIN 
CASE selector OF 
hilightSel: {hilight the characters selected by the custom pack. } 
{paramptr=pointer to text to select, paramwordléparamword2=start,end 
chars} 
WITH textH** DO 
{we'll subtract the start of text from paramptr to get the base 
offset...} 
TESetSelect (ORD(paramptr) - StripAddress (ORD (hText^)) + 
paramwordl, ORD(paramptr) - StripAddress (ORD (hText^)) 
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+ paramword2,textH) ; 


notifySel: {put up message per request from custom pack. } 
{paramptr points to string to display} 
ShowADialog (infoDLOG) ; 


END; {CASE} 
END; {CustDispatch} 


BEGIN {main program} 

{ Initialization } 

InitGraf (@thePort); {initialize QuickDraw} 

InitFonts; {initialize Font Manager} 

FlushEvents (everyEvent - diskMask,0); {call OS Event Mgr to discard 

non-disk-inserted events} 

InitWindows; {initialize Window Manager} 

InitMenus; {initialize Menu Manager} 

TEInit; {initialize TextEdit} 

InitDialogs(NIL); {initialize Dialog Manager} 

InitCursor; {call QuickDraw to make cursor (pointer) an arrow} 


InitSignals; 

errCode := CatchSignal; 

IF errCode <> 0 THEN BEGIN 
Debugger; 
Exit (P); 

END; 


SetUpMenus; {set up menus and menu bar} 
UnLoadSeg (@SetUpMenus); {remove the once-only code} 


{Custom package initialization stuff} 

appdispatch := @CustDispatch; 

CustomInit (69, custhandle); {should test custhandle for NIL and alert 
the user} 

GlogString := ''; 


{etc. with the rest of initialization and the main event loop} 


END. 


Technical Note #135 page 7 of 14 Custom Packages 


; now for the assembly language code 

; first, the dispatching and initializing code that must be linked into 
the application 

; CustomCalling 

; Custom packages initializing and dispatching 


~> 


Rick Blair May, 1987 


PRINT OFF 

INCLUDE 'Traps.a' 
INCLUDE 'ToolEqu.a' 
INCLUDE 'QuickEqu.a' 
INCLUDE 'SysEqu.a' 


ta wa we ē We ē S ē ™e Wg ™p 


PRINT ON 
LOAD 'most.dmp' ; from a dump of the files above 
appdata EQU 12 


Initialize a custom module 
Pascal call format: 
CustomiInit (resID:INTEGER;VAR custhandle: Handle) ; 


This will load the CUST module with the given resource ID, install a 
handle to it in custhandle, and set the module’s appdata pointer to 
point to the address appaddr. 


we wg we >g ē ag i in, iT | 


resID EQU 8 
custhandle EQU 4 
CustomInit PROC EXPORT 
SUBQ.L #4,A7 ;smake room for handle from GetResource 


MOVE.L  #'CUST',-(A7} 

MOVE.W resID+8 (A7),-(A7);resource ID 
_GetResource 

MOVE.L (A7)+,A0 

MOVE.L custhandle(A7),Al 


MOVE.L AQ, (Al) 7store handle in app’s custhandle global 
; (return with nil handle if GR failed) 

MOVE.L (A7)},A0 ¿get return address 

ADD.L #10,A7 ¿strip everything 

JMP (AQ) jadieu 


;Call a custom module 

;Pascal format: 

; CustomCall( {parameters as desired} selector: INTEGER; appaddr: Ptr; 
: module: Handle); 

:This will call the code whose handle is passed on the stack. If the 
;application was written in assembly language you would just 
dereference the handle and call it directly (you wouldn’t need this at 
7 all). 


CustomCall PROC EXPORT 
IMPORT Signal 
MOVE.L 4(A7),A0 ¿get handle 
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MOVE.L {A0),D0 


BNE .S @0 zif hasna’ been purged, ga’ ahead 

MOVE.L A0O,-{A7)} ;push handle 

_LoadResource 

MOVE.W ResErr,- (A7) 

JSR Signal ¿Signal is a NOP if a zero is passed to it 


MOVE.L 4(A7),A0 shandle again 
; we don't lock the handie here (we can't save it so we can unlock it 
; later), so it's up to the package to lock/unlock itself 


@0 MOVE.L (A0Q),A0 ;dereference 
JMP (AQ) ;call CUST code 
END 


here is the module for the custom package itself 


~s 


CustomPack 
Example custom code package 


we 


~é ~g we 


Rick Blair May, 1987 


; This demonstrates the recommend structure of a code module which a 

; sophisticated user could add to an existing application which supported 
> this mechanism. Aside from allowing for multiple routines within the 

; module (via a selector), provision is made for calling a routine 

; dispatcher within the application itself. 


;Finding text 

;We support a call to find a string anywhere within a block of text 

> (selector=0), and one to find the string only as a separate "word" 

; with spaces around it (selector=1). 

; PROCEDURE CustomCall(text:Ptr; count:INTEGER; findstr: “STRING; 

; selector:INTEGER; appaddr: UNIV Ptr; ourhandle:Handle); 
Rather than return a result indicating whether they succeeded or not, 
these routines take whatever action is appropriate (the application 

;may not even know what these routines actually do). 

Once a call succeeds or fails, it then takes action by making a call to 
sone of the services provided by the application. In this case the two 
:functions provided are just what we need; the ability to select text and 
;the ability to put up a message saying "Text not found". 


STRING ASIS 


A PRINT OFF 
; INCLUDE 'Traps.a' 
: INCLUDE 'ToolEqu.a' 
; INCLUDE 'QuickEqu.a' 
: INCLUDE ‘'SysEqu.a’ 
: PRINT ON 
LOAD 'most.dmp' ; from a dump of the files above 
CustPack PROC EXPORT 
BRA.S Entry ;skip header 
DC.W 0 ;flags 
DC.B CUST ;custom add-on code module 
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DC .W 69 ¿resource ID (picked by Mr. Peabody & 
; Sherman) 
DC .W $10 ¿version 1.0 


StackFrame RECORD {A6Link},DECR 


paramsize EQU žk- 
; call-specific parameters... (optional) 
text DS.L 1 ;pointer to text block 
count DS .W 1 ¡word count of characters in text 
findstr DS.L 1 spointer to p-string to find 
; selector (word, optional - you might only have 1 call) 
selector DS.W 1 
EcharsCmd EQU 1 ; selector for "find characters" 
fwordCmd EQU 2 ; selector for "find word" 
; pointer to app. globals (long) 
appaddr DS.L 1 
; handle to this resource (long) 
ourhandle DS.L 1 
; TOS:return address (long) 
return DS.L 1 
;the stack link is built off the origin of the saved old A6 on the stack 
A6Link DS.L 1 
LocalSize EQU * 
ENDR 


;offsets into our application globals area 
AppGlobals RECORD {appdispatch},DECR 
appdispatch DS.L 1 


paramptr DS.L 1 
paramwordl DS.W 1 
paramword2 DS.W 1 
;CUSTerr DS .W 1 ¿if we had possible errors 
ENDR 
Entry 
WITH StackFrame, AppGlobals 
LINK A6, #LocalSize 
- MOVEM.L ... ¿we'd save any non-trashable regs here 


¿first lock us down... 
MOVE.L ourhandle (A6), A0 
_HLock 


MOVE.W selector(A6),D0 
CMP .W #f£charsCmd, D0 
BEO.S charfind ;go find characters 
CMP .W #fwordCmd, DO 
BEQ.S wordfind go find a word 
;well, M. App didn’t call us with a selector we know, So... 


sunlock ourselves, clean up, return 
: (if we wanted to return an error code we could stuff it into the app. 


; global area) 


duhn MOVE.L ourhandle (A6é),A0 
HUnLock 

; MOVEM.L ... ¿restore any registers here 
UNLK A6 


MOVE.L (A7)+,A0 sreturn address 


Technical Note #135 page 10 of 14 Custom Packages 


ADD .L #paramsize,A7;strip parameters 
JMP (AQ) 


;selector codes for calls to application 
hilight EQU 0 shighlight characters, please 
notify EQU 1 ;beep a little 


;find the string "findstr" anywhere in the block "text" 


charfind 
JSR findchars ;see if findstr is anywhere in text 
BEQ.S nofind zif not then skip 
JSR calcsels ;compute selstart and selend 

didfind MOVE.L appaddr(A6),A0 ;get pointer to appl. globals area 
MOVE.L text (A6),paramptr({A0) ;setup text pointer and.. 
MOVE.W D0,paramwordil (A0) ;start character position, 
MOVE.W D1,paramword2(A0) ;end character position 
MOVE.W #hilight,-(A7) ;pass proper selector 

goapp MOVE.L appdispatch(A0),A0 ;get dispatch address 
JSR (A0) ¢call the application to select the range 
BRA.S duhn ;return to application (deja vu) 

nofind MOVE.L appaddr(A6),A0 ;get pointer to appl. globals area 
LEA oopstring, Al ;get pointer to "Not found" message 


MOVE.L Al,paramptr(A0) ;put string pointer in “paramptr” 
MOVE.W #notify,-(A7) ;tell app. to display message 
BRA.S goapp 


;figure selstart and selend 

calcsels NEG .W DO ;negate # characters unskipped in text 
SUBQ.W #1,D0 ¿include lst character 
ADD .W count (A6),D0;compute 1st character position for select 
MOVE.L findstr(A6),Al 


MOVE.B (Al1),D1 ;get length of string 

EXT .W D1 

ADD .W D0,D1 :compute last char. pos. for select 
RTS 


;find the characters, but only if surrounded by space (including end or 


; beg.) 
swe could extend the test to check for other delimiters (yet oR ets.) 
wordfind 
JSR findchars 
wloop BEQ.S nofind 
MOVE.W D0,D2 ;save count of text remaining 
JSR calcsels ;figure start and end offsets 
MOVE.L text(A6),Al ;point to text 
TST .W DO ;start=beginning of text? 
BEQ.S @0 ; yep, 30 it passes 
CMP .B #' ',.-1(A1,D0) ;preceded by a space? 
BNE.S G1 znope, keep looking 
@0 CMP .W count (A6),D1 ;Dl=length of text? 
BEQ.S didfind ;yep, so it passes 
CMP .B #' ', (Al,D1) ;followed by a space? 
BEQ.S adidfind ;yes, so we've found it 


:this wasn’t paydirt, so keep panning 
Q1 MOVE.W D2,D0 ¿restore chars remaining count 
BMI.S nofind ;forget it if we ran out of text 
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JSR 
BRA.S 


bigloop 
wloop 


;keep looking 


sthis code will find the string if it lies anywhere in the text 
text (A6),A0 ;point A0 to chars to search 
count (A6),D0;size of text block 
findstr(A6),Al;point Al to chars to find 


findchars 


bigloop 


;search for 


MOVE.L 
MOVE .W 
MOVE.L 
MOVE .W 
CMP .W 

BGT.S 

ADDQ.L 
BRA 


(Al)+,D1 
#255,D1 
@1 

#4,A7 
duhn 


first character 


;get length byte and 1st char. (skip ‘em) 
zenter loop if length<>0 

;strip findchar’s return address 

;return having done nothing 


eo CMP .B (A0)+,D1 sthis one match lst character? 
@1 DBEQ D0, QO ¿branch until found or done ‘em all 
BNE.S cnofind ;skip out if no match on lst character 
MOVE.B <-2(Al1),D1 ; length of findstr 
EXT .W Di 
SUBQ.W #1,D1 ;length sans lst character 
BEQ. S cfound ;if Length(findstr)=1, we’re done 
CMP.W D1,D0 
BLT.S cnofind ¿fail if findstr is longer than text left 
MOVE.L  A0,D2 ;savę this character position 
CMP.W D1,D1 ¿force EQuality 
BRA.S @3 ;enter loop 
@2 CMP .B (A0)+, (Al)+ ;match so far? 
@3 DBNE D1, @2 scheck until mismatch or end of findstr 
MOVEA.L D2,A0 ;restore position (cc's unaffected) 
BNE.S bigloop ;if no match then keep looking 
cfound MOVEQ #1,D1 ¿return TRUE 
RTS 
cnofind SUB. W D1,D1 ¿return FALSE 
RTS 
STRING PASCAL 
oopstring DC.B "Pattern not found.’ 
END 


additions to the resource file 


"DLOG' 
{72, 64, 
daBoxProc, 
visible, 
noGoAway, 
0x0, 

129, 


(129, 


"Find dialog") { 
428}, 


resource 
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"Find" 


resource 'DLOG' (130, “"Info™) { 
{66, 102, 224, 400}, 


dboxproc, visible, nogoaway, 0x0, 


}? 


resource 'DITL’ (130) { 
{ 
/* 1 */f {130, 205, 150, 284}, 
button { 
enabled, 
"OK already” 
}3 
/* 2 */ {8, 32, 120, 296}, 
/* info */ 
statictext { 
disabled, 


}? 


resource 'DITL' (129) { 


150, “m 


{ /* array DITLarray: 4 elements */ 


/* [1] */ 

{64, 48, 84, 121}, 

Button { 
enabled, 
"OK" 

}; 

/* [2] */ 

{64, 231, 84, 304}, 

Button { 
enabled, 
"Cancel" 

} 7; 

/* fay FF 

{8, 8, 24, 352}, 

StaticText { 
disabled, 
"Find what?" 

}? 

/* [4] */ 

{32, 8, 48, 352}, 

EditText { 
disabled, 


}? 


resource ‘MENU’ (131, "Custom", preload) 
131, textMenuProc, 0x3, enabled, 


{ 
"Find Chars...", 
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noicon, “F", nomark, plain; 
"Find Word..", 
noicon, "W", nomark, plain 


F- 


type 'CTST' as ‘STR '; 


resource 'CTST' (0) { 
“Custom Application - Version 1.0" 
}; 


include "CustomPack.code"; 


# This makefile puts the program together incl. the CUST pack. 


CustomTest ff CustomCalling.a.o CustomTest.p.o ErrSignal.a.o 
# the predefined rule for assembly will build CustomCalling.a.o, 
# CustomPack.code 
Link CustomTest.p.o CustomCalling.a.o ErrSignal.a.o ð 
"{Libraries}"Interface.o ð 
"{Libraries}"Runtime.o ð 
"{PLibraries}"Paslib.o ð 
-o CustomTest 
CustomPack.code f CustomPack.a.o 
Link CustomPack.a.o -rt CUST=69 -o CustomPack.code 
# Put the resource file together (including the custom code resource) 
CustomTest Ff CustomTest.r CustomPack.code 
Rez CustomTest.r -a -o CustomTest 
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#136: Depending on Register a5 Within GrowZone Functions 


See also: The Memory Manager 
Technical Note #25—Register a5 Within Trap Patches 


Written by: Chris Derossi July 1, 1987 





lf you have a grow zone function, it may get called when a system routine is trying to 
allocate memory. Because this can happen, you can’t be guaranteed that register A5 
will be correct. 


if your grow zone function depends on A5, you should save register A5, load A5 from 
the low-memory global Currenta5 (along word at $904), and restore the caller’s A5 
before you exit. 

From high-level languages, you can also use the Operating System Utility calls 
SetUpA5 and RestoreaS (Inside Macintosh Pg II-386). Set UpAS stores the ‘old’ AS on 
the stack and puts the value stored at Currentas into AS. Make sure to call RestoreA5 
when you're done so that it can pop the saved value of A5 off the stack. 

Your grow zone function depends on As if it does any of the following: 


e Accesses your application’s global variables (which are stored at negative 
offsets from AS). 


e Accesses the QuickDraw globals. (A5 contains the address of a pointer to the 
QuickDraw global variables.) 


e Makes any ROM trap calls. 
¢ Makes any intersegment calls to routines in your application. 
To do any of these, A5 needs to contain the value from CurrentAs. Please note that 


this is different than the method for calling the ROM from trap patches, where A5 should 
retain the value it had upon entry to your patch. 
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#137: AppleShare 1.1 Server FPMove Bug 


See also: AppleTalk Filing Protocol (available from APDA) 
Written by: Rich Andrews June 16, 1987 
Modified by: Bryan Stearns July 1, 1987 


| tate 


A bug has been discovered in AppleShare 1.1’s implementation of the 
AppleTalk Filing Protocol FPMove call. This bug only affects developers 
working on implementing custom workstation access code that will access 
AppleShare 1.1 servers from non-Macintosh systems (such as MS-DOS 
systems); if the guidelines below are not followed, data loss may result. 





The AppleShare file server.supports an AFP call known as FPMove, used to move a file 
or directory tree from one place to another on an AppleShare volume. In addition to 
moving, the caller can specify a new name for the file or directory being moved; in 
essence, a move and a rename can be accomplished by a single call. 


The AppleShare 1.1 server implements this call as follows: the file is moved from the 
source directory to an invisible holding directory, renamed, then moved to the destination 
directory. The problem occurs when a locked file is moved and renamed in this manner: 
the initial move succeeds, the rename fails, and the file is left in the holding directory 
(essentially lost, as it will be deleted when the server is shut down). 


Macintosh AppleShare 1.1 workstation software never uses the move-and-rename 
combination, so this problem cannot occur on a Macintosh; however, if you're 
implementing your own workstation-access software for some other machine or 
operating system, and wish to use this feature, you must follow this procedure: 


When a move and rename call comes from the native file system, issue an 
FPGetFileDirParms Call to see if the object is a locked file. If it is, issue an 
FPSetFileParms Call to unlock the file. Then issue the FPMove Call, followed by another 
FPSetFileParms Call to lock the file again. 


AFP does not allow locked files to be renamed, whereas some native file systems (such 
as MS-DOS) do. You must therefore preflight for this condition to maintain transparency. 


This problem will be corrected in a future version of the AppleShare server software. 
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#138: Using KanjiTalk with a non-Japanese Macintosh Plus 


see also: KanjiTalk Usage Notes 
Script Manager Developers Package—available from APDA 


Written by: Priscilla Oppenheimer July 1, 1987 





 — M 


This Technical Note describes the minor differences between using 
KanjiTalk with the Japanese Macintosh Plus and KanjiTalk with a standard 
Macintosh Plus. 





There are two differences between the Japanese Macintosh Plus and the standard 
Macintosh Plus: The Japanese Macintosh Plus has the Kanji 12 and 18 point fonts in 
ROM and it is shipped with the Kana keyboard. It is not necessary to have this 
keyboard in order to use KanjiTalk. (See the KanjiTalk Usage Notes for details on how 
to use it with a non-Kana keyboard.) It is, however, necessary to have 12 point Kanji in 
order to use KanjiTalk; the 18 point Kanji is optional. 


When using KanjiTalk with a standard (non-Japanese) Macintosh, the user supplies 
these fonts on disk and the Macintosh loads them into RAM. At boot time, the 
Macintosh looks for the 12 point Kanji font file in the System Folder of the boot disk. If it 
cannot find the font, it will look through the root directory of all mounted volumes. (The 
font has to be at the root level: it cannot be in a folder.) If it still doesn’t find the font, it 
will prompt the user to insert a disk with the font file in the root directory. Once 
KanjiTalk finds the 12 point font, it will go through the same process looking for the 18 
point font. The user can cancel this search if the optional 18 point font is not necessary. 


When KanjiTalk finds the fonts, it loads them into memory. The 12 point font takes up 
approximately 100K of memory and the optional 18 point font takes up approximately 
250K of memory. The KanjiTalk code itself takes up about 180K of memory. Because 
the fonts take up quite a bit of memory, many applications will not work on a Macintosh 
512K with the Kanji fonts installed. 


Accessing the fonts from ROM is faster, but we have not noticed any significant speed 
problems when the fonts are accessed from RAM. There is, however, a noticeable 
difference in speed when the Macintosh is booted. It takes a couple of seconds to load 
the 12 point font and about 6 seconds to load the 18 point font. 


Note that the Japanese Macintosh is unique; Apple has not produced any other foreign 
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versions of the Macintosh for different scripts. The introduction of the Arabic Interface 
System, for example, did not include an Arabic ROM version. 
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#139: Macintosh Plus ROMs 
Written by: Cameron Birse July 1, 1987 





Readers Digest condensed version of the Macintosh Plus ROM history, or the truth 
according to Bo3bdar the everpresent: 


1st version (Lonely Hearts, checksum 4D 1E EE E1): 


Bug in the SCSI driver, Machine won't boot if external drive is turned off. We only 
produced about one and a half months worth of these. 


2nd version (Lonely Heifers, checksum 4D 1E EA E1): 
Fixed boot bug. This version is the vast majority of beige Macintosh Pluses. 
3rd version (Loud Harmonicas, checksum 4D 1F 81 72): 
Fixed bug for drives that return Unit Attention on power up or reset. Basically took the 
SCSI bus Reset command out of the boot sequence loop, so it will only reset once 
during boot sequence. This version shipped with the platinum Macintosh Pluses. 
And BoSbdar saith: “Thou shalt not rev them damn ROMs no more!” 
Later that same day... 
BoSbdar Saith Also: 
Lonely Heifer was about a 2 byte change, 
Loud Harmonica was about 30 byte change. 
No other bug fixes in SCSI or elsewhere. 
Modified object code directly. 
Not possible to get a specific ROM since they are ali the same part number. 


Shouldn't rely on a specific ROM, there will be no upgrade. 
Bo3b Bo3b a boola, a wiff Ba2m Bolom. 
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#140: Why PBHSetVol is Dangerous 
See also: The File Manager 


Written by: Chris Derossi July 1, 1987 





This technical note explains what PBHSetvol does, and why its use is not 
recommended. 
eee 


—_——_— e 


PBHSet Vol, like Set Vol and PBSet Vol, allows you to set the current default volume 
and directory to be used with subsequent File Manager calls. Unlike Ssetvol and 
PBSetVol, though, PBHSetVol lets you specify the volume and the directory 
separately, using the iovRefNum and ioWDDirID fields. 


PBHSetVol lets you specify a WORefNum for the iovRefNum in addition to a partial 
pathname in ioNamePtr. PBHSetVol will start at the specified working directory and 
use the partial pathname to determine the final directory. This directory might not 
correspond to an already existing working directory, so the File Manager cannot refer to 
this directory with a wWDRefNum. Instead it must use the actual volume refNum and the 
DirID number (which is assigned when the directory is created, and doesn’t change). 


The net effect of all of this is, if you call PBHSet Vol, the File Manager stores the actual 
volume RefNum as the default volume, and the default DirID separately. This happens 
on all calls to PBHSet Vol. Subsequent calls to Get Vol or PBGet Vol will return only the 
volume RefNum in the LOVRe£fNum field of the parameter block. If any code tries to use 
the RefNum returned by Get Vol, it will be accessing the root of the volume, and not the 
current default directory as expected. 


This is particularly nasty for desk accessories because they don’t know that your code 
has called PBHSet Vol and they don’t get what they expect if they call Get Vol. 


It is therefore recommended that you avoid using PBHSet Vol because of this side 


effect. None of the other ‘H’ calls that allow you to specify a DirIp do this, so they're still 
OK. 
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#141: Maximum number of resources allowed in a file 
See also: The Resource Manager 


Written by: Cameron Birse July 1, 1987 





This technical note describes the limitation of the number of resources in a 
single file. 





There is a limit to the number of the resources allowed in a single resource file. This 
limitation is imposed by the resource map, and this technote will explain the limitation. 
On page 128 of Inside Macintosh Volume |, there is a description of the format of a 
resource file. At the bottom of page 129 is the resource map description. There are two 
bytes at the end of the map which are the offset from the beginning of the resource map 
to the beginning of the resource names list. If there is only one type of resource, then the 
overhead from the beginning of the resource map to the beginning of the reference list is 
38 bytes. Since the offset is a two byte value, and it is a SIGNED number, its highest 
value possible is 32768. This is where the limitation is. If you subtract 38 bytes for the 
overhead, and divide the difference by 12 (the number of bytes for each reference) you 
get 2727.5, therefore, the limit to the number of resources in a single file is 2727. 


The resource manager was not intended to manage very large numbers of resources, 
and as a result, its speed performance is particularly bad with large numbers of 
resources. Because of these restrictions, we recommend that developers avoid using 
the resource manager as a data base tool. 
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#142: Avoid Use of Network Events 
See also: AppleTalk Manager 
Written by: Bryan Stearns July 1, 1987 





eevee 


Future System software enhancements will not support network events. This 
note gives hints on weaning your application from the use of network events. 





a 


What are network events? 


When the Event Manager was designed, an event number was reserved for future 
support of “network events”. Later, when the AppleTalk Pascal Interfaces were written, a 
completion routine was created that, when an asynchronous AppleTaik operation 
finished, would post an event using networkEvt in the evt Nun field. 


Only the AppleTalk Pascal Interfaces generate network events. Assembly-language 
users of the AppleTalk drivers (and those who called the AppleTalk drivers directly from 
high-level languages, using PBControl Calls) either provide a completion routine of 
their own, or poll the ioResult field of the parameter block passed with the call (when 
ioResult became negative or zero, the call is complete). 


Why not use network events? 


In some cases, network events can be lost. If the Event Manager finds that the queue is 
full while posting an event, it discards the oldest event. In a situation (such as a server) 
where multiple asynchronous ATP requests may complete at once, there is a chance that 
events may be dropped off the end of the queue. This is more likely if the same machine 
is also handling user-interface events (like keypresses and mouse actions). 


Also, in developing improvements to our operating system, it has become apparent that 
to continue support of network events, we would have to compromise future 
enhancements to our system. So, future versions of the Macintosh operating system may 
ignore network events instead of passing them to the application. 
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How can | tell that my calls have completed without using network 
events? 


As described on page !I-275 of Inside Macintosh, you can poll the abResult field of the 
call’s ABusRecord; when this value becomes negative or zero, the call has completed. 
You can do this in your main event loop. 


With this technique, you can ignore any network events returned by GetNextEvent, 
since the AppleTalk Pascal Interfaces will be posting events anyway. If your application 
starts enough asynchronous operations, it’s possible that their network events will cause 
other non-network events to be lost. To prevent this, you should call 
FlushEvents (networkMask,0) frequently to purge any accumulated network events 
from the event queue. 


You may also consider using the new preferred high-level interface calls; see Technical 
Note #132 for more information. 
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#143: Don't call ADBRelnit on the Macintosh SE with System 4.1 
See also: The Apple Desktop Bus 
Written by: Mark Baumwell July 1, 1987 





Because of a bug (which causes auto-repeat) in the ROM version of the Macintosh SE 
keyboard driver, a patch was placed in System 4.1. If ADBReInit is called, the ROM 
version of the keyboard driver will be reloaded, and the RAM version of the driver with 
the patches will not be used. Therefore, it is recommended that ADBReInit not be 
called on the Macintosh SE until the problem is fixed. (There is no need to call 
ADBReiInit.) This problem will not occur with the Macintosh Il ROM version of the 
keyboard driver. 
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#144: Macintosh I! Color Monitor hookups 


See also: Macintosh Il and Macintosh SE Cards and Drivers 
Macintosh Hardware Reference 


Written by: Mark Baumwell July 1, 1987 





This technical note describes how to connect the Macintosh II Video Card to 
third-party monitors. 


—— 


Here are the pin outs of the Macintosh Il Video Card (15-pin D connector): 


Macintosh Il 

Video Card Pin Signal Name 
1,4,6,11,13,14 Ground 

2 Red 

3 CSync— (composite sync) 
5,12 Green (with sync) 

9 Blue 

7,8,10,15 Not connected 


Sony Multiscan (CPD-1 302) 


To hook a Sony Multiscan monitor to a Macintosh lIl, you will need to make an adapter 
cable from the video card to the monitor (which has a 9-pin D connector). 


Here is the pin out description for the adapter cable (using the automatic sync-on-green 
configuration): 


Macintosh Il Sony 

Video Card Pin Pin Signal Name 
1 1 Ground 

2 3 Red 

5 4 Green (sync) 
9 5 Blue 
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NEC MultiSync (JC-1401IP3A) 


To hook an NEC Multisync monitor to a Macintosh Il, you will again need to make an 
adapter cable from the video card to the monitor (which has a 9-pin D connector). 


Here is the pin out description for the adapter cable (using the sync-on-green 
configuration): 


Macintosh Il NEC 

Video Card Pin Pin Signal Name 
1 6,7,8,9 Ground 

2 1 Red 

5 2 Green (sync) 
9 3 Blue 


The monitor must be set to Analog mode and manual mode. The above adapter cable 
will also work with an equivalent monitor such as the Taxan Super Vision 770. 
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#145: Debugger FKEY 
Written by: Mark Baumwell July 1, 1987 


It is often more convenient to enter the debugger using the keyboard rather 
than having to reach around to press the interrupt switch. This technical 
note shows how to make a simple FKEY that will trap to the debugger. 


This technical note shows how to make a simple FKEY that will trap to the debugger. It 
is written in MDS 2.0. The listings for the assembler source, linker contro! source, and 
resource definition source are given below. 


Assembler source file listing: 


File: DebuggerFKEY.Asm 
An FKEY to invoke the debugger via command-shift-8 


To build: 
1. Assemble this file 
2. Run the linker with the linker control file (DebuggerFKEY.Link) 
3. Run RMaker using DebuggerFKEY.r as input file 
4. Paste the FKEY into the System file with Resource editor 


we Se “es Se Se Bea Bea Se Se 


BRA.S CallDB ; Invoke the debugger 
;standard header 
DC.W $0000 ; flags 
DC.L 'FKEY' ; 'FKEY' is 464B4559 hex 
DC .W $0008 ;FKEY Number 
DC .W $0000 ;Version number 
CallDB DC.W SASEFF ;Debugger trap 
RTS 
END 
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Linker control file listing: 
; File: DebuggerFKEY. Link 
; Linker control file 


; (tells the Linker what files to link, segmentation 
; info, etc) 


; Output file name 
/Output DebuggerFKEY.Linked 


; .Rel file(s) that are input to the linker 
DebuggerFKEY 
zend of Linker control file 


$ 


RMaker resource definition file listing: 


* File: DebuggerFKEY.R 

* 

* Resource file for Debugger FKEY 

* 

* Output file name (that will contain the FKEY resource) 


DebuggerFKEY 


TYPE FKEY = PROC 7; PROC takes CODE 1, strips off header 
,8 ;; resource id, attributes 
DebuggerFKEY. Linked ;; file name (was output from the linker) 
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#146: Notes on MPW Pascal’s -mc68881 Option 


see also: Apple Numerics Manual 
MPW Pascal 2.0 Reference (APDA) 


Written by: . Bryan Stearns July 1, 1987 





For improved performance, the MPW 2.0 Pascal compiler represents 
Extended values in 96 bits (instead of 80, as with software SANE) when the 
-mc 68881 option is used. This can cause problems when using non-SANE 
system calls that expect 80-bit Ext ended values. 





The Pascal Compiler and Extended values 

The MPW 2.0 Pascal compiler provides a command-line option, -mc68881, to generate 
inline code to use the Motorola 68881 Floating-Point Coprocessor {included with 
Macintosh Il). This allows you to sacrifice compatibility with other Macintosh systems 
(those not equipped with the 68020/68881 combination) in exchange for 
much-increased numeric performance. 


When this option is used, the compiler stores all Extended values in the 96-bit format 
used by the 68881, instead of the 80-bit software SANE format: 


79 78 63 0 
1-bit 15-bit 64-bit 
sign exponent mantissa 
80-bit Software SANE Format 


95 94 79 63 0 
1-bit 15-bit Y 16-bit 64-bit 
sign exponent ZERO tf mantissa 


96-bit 68881 Format 





This affects all procedures that accept floating-point values as arguments, since all 
floating-point arguments are converted to Ext ended before being passed, no matter how 
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they're declared (that is, real, single, double, Or comp). 


You must link with a special SANELib library file (“SANE881Lib.o”) when compiling with 
this option; the interface source file “SANE.p” contains conditional-compilation 
statements to make sure that the correct library’s interface is compiled. In this situation, 
SANE procedures are used for certain transcendental functions only (see note below), 
and these functions (in “SANE881Lib.o”) expect their Extended parameters in 96-bit 
format. 


However, numeric routines that are not compiled by Pascal (such as any 
assembly-language routines that you've written) have no way of finding out that their 
parameters will be in 96-bit format. If you don’t wish to (or can’t) rewrite these routines for 
96-bit values, you can use the SANELib routines x96ToxX80 and x80Tox96 to Convert 
back and forth; it might be simplest to define a new interface routine to make the 
conversions happen automatically: 


{* An assembly-language function that accepts *} 
{* an 80-bit Extended parameter and returns an *} 
{* 80-bit result (We've changed the types to *) 
{* reflect that these are not 96-bit values). *} 
FUNCTION FPFunc(x: Extended80): Extended80; EXTERNAL; 


{* Given that we're compiling in -mc68881 mode, *} 


{* call our assembly-language function. Note *} 

{* that the compiler thinks that Extended *} 

{* values are 96 bits long, but FPFunc wants an *} 

{* 80-bit parameter and produces an 80-bit *} 

{* result; we convert. *} 

FUNCTION FPFunc96(x: Extended): Extended; {x is a 96-bit extended! } 
BEGIN 


{convert our argument, call the function, then convert the result} 
MyFPFunc := X80ToOX96 (FPFunc (X96TOX80 (x))); {call the real FPFunc} 
END; 


It's best to avoid compiling some parts of an application with the -mc68881 option on, 
and other parts with it off; very strange bugs can occur if you try this. Note that 80-bit code 


and 96-bit code cannot reference the same Extended variables. There is no way to tell 
whether a given stored value is in 80-bit format or 96-bit format. . 


SANE on Macintosh Il 

The version of SANE provided in the Macintosh Il ROM recognizes the presence of the 
68881 and uses it for most calculations automatically. SANE still expects (and produces) 
80-bit-format Extended values; it converts to and from 96-bit format internally when 
using the 68881. 

A Note about 68881 Accuracy and Numeric Compatibility 

SANE is more accurate than the 68881 when calculating results of certain functions (Sin, 
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Cos, Arctan, Exp, Ln, Tan, Exp1, Exp2, Ln1, and Log2). To maintain this accuracy, SANE 
doesn’t use 68881 instructions to directly perform these functions. Thus, the results you'll 
get from SANE calculations will still be identical on all Macintosh systems. 


To preserve this numeric compatibility with other SANE implementations, MPW Pascal 
normally doesn't generate inline 68881 calls to the above functions, even when the 
-mc68881 option is used; instead, it generates SANE calls to accomplish them. If you're 
willing to sacrifice numeric compatibility to gain extra speed, you can override this 
compiler feature with the compile-time variable Elems881; include the option “-d 
Elems881=TRUE” on the compiler command line to cause the compiler to generate direct 
68881 instructions. 


For certain other transcendental functions provided by the 68881 that aren't provided by 
SANE, MPW Pascal will generate direct 68881 calls if the -mc68881 option is on, 
independent of the setting of the Elems881 variable. These operations are Arctanh, 
Cosh, Sinh, Tanh, Logi0, Exp10, Arccos, Arcsin, and Sincos. 
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#147: Finder Notes: “Get Info” Default & Icon Masks 
See also: Technical Note #48—Bundles 
Written by: Bryan Stearns July 1, 1987 


mirr 


The Finder will be undergoing a couple of changes you should keep in mind 
when creating the “bundle” information for your application. 


Creator String will be the default “Get Info” comment text 


The “creator” (or “signature”) string (contained in a resource whose type is your 
application’s four-character creator type, and whose ID is 0) will be used as the default 
for the comment text displayed by the Finder's “Get Info” command. Thus, you should set 
up this string (when you build your application) to contain the name of your program and 
a version number and date. 


Icon Masks should match their icons 


Your application’s BNDL (“bundle”) resource ties the file types that it uses for its 
documents with the icons to be displayed for those documents. For each icon, a “mask” 
icon is also provided; this mask is used to punch a hole in the gray desktop before 
drawing the icon. 


Some applications use a cleverly-modified mask to provide an “action icon” that looks 
different when it’s selected. This will cause problems in the future in color environments; 
it is important that the mask be what it’s supposed to be (that is, a solid black copy of the 
icon, containing no holes). 
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#148: Macintosh II expansion port cover suppliers 
See also: Macintosh I! and Macintosh SE Cards and Drivers 


Written by: Mark Baumwell July 1, 1987 





This technical note lists suppliers for Macintosh II board developers. If your 
company supplies these parts, but is not listed here, please send a message 
to us (at the address on Technical Note 0) and we'll include you in the next 
revision of this technical note. 





= a 


This is a list of companies that supply the Macintosh Il expansion port cover (p/n 
805-5064-05) (Figure 7-2 in Macintosh Il and Macintosh SE Cards and Drivers 
manual). It is not intended to be an endorsement or an indication of quality; it is just our 
list of known suppliers. 


Galgon Industries, Inc. 

37399 Centraimont Place 
Fremont, CA 94536 

Attn: Ron Haddox—General Sales 
(415) 792-8211 | 


Vector Electronics 
12460 Gladstone Ave 
Sylmar, CA 91342 
(818) 365-9661 
FAX# 818-356-5718 
Attn: Norm Brunell 


North American Tool and Die 
999 Beecher Street 

San Leandro, CA 94577 
(415) 632-9263 

Attn: Glenn Enkson 


In addition to supplying the expansion port cover, Vector Electronics supplies 
Macintosh II NuBus extender boards and prototyping boards. 
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#149: Document Names and the Printing Manager 


See also: Printing Manager 
Technical Note #122—Device- -Independent Printing 


Written by: Bryan Stearns July 1, 1987 


maa 


Our compatibility testing for LaserShare (Apple's LaserWriter spooler) has 
turned up a number of applications that do not provide the Printing Manager 
with a document name; although this feature is not required, it is nice for your 
users that share printers. 


The Printing Manager obtains the document's name from the front window's 
title during Prvalidate; supplying your document's name there is most likely 
to be supported under future printing architectures, and is printer- 
independent. 


Some printers (usually those that are shared between many users, like the LaserWriter) 
can provide the names of the users who are printing and the documents that are being 
printed to others interested in using the printer. 


if the chosen printer uses a document name, the Printing Manager gets the name from 
the frontmost window’s title. If there is no front window, or if the window’s title is empty, 
the Printing Manager defaults to “unknown.” 


This method was chosen because it works most transparently to applications; however, it 
won't work if your application doesn’t display windows when printing (for instance, many 
applications that use windows for their documents do not open their documents when 
printing in response to a Finder “print” command). 


As a general solution to this problem, you can put up a window containing a message 
like “Press 3-—. to cance! printing”, and give it the document's title. If the window 
definition ID is one that doesn’t have a title bar (like dBoxProc), this title will not be 
displayed. MacApp takes this approach. 


if for some reason you don’t want to put up a visible window, you can create a tiny 
window and hide it behind the menu bar: for instance, global coordinates of (1,1,2,2). 
Make sure you use plainDBox as the window definition ID, so that no title will be drawn 
(otherwise, in the unlikely case that a user is using a Macintosh II with two stacked 
screens, main screen on the bottom, the title might be visible on the upper screen). 


Technical Note #149 page 1 of 2 Document Names and the Printing Manager 


Since the Printing Manager only checks the name at Prvalidate time, you should call 
PrValidate after PrCloseDoc and before the next PrOpenDoc, if you want unique 
names. 


A number of applications set the document name in the print record directly. You should 
not do this because a) not all printers support this field, and b) none are guaranteed to 
support it in the future. (Apple does not guarantee that the internal fields of the Printing 
Manager's data structures will remain the same; be warned that the Printing Manager is 
targeted for substantial internal change!) 
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#150: Macintosh SE floppy disk driver bug 
Written by: Mark Baumwell July 1, 1987 


The Macintosh SE ROM floppy disk driver incorrectly de-selects the upper 
drive in a two floppy disk drive Macintosh SE; this results in the upper disk 
drive being slower than the lower drive. 


In a Macintosh SE with the two floppy disk drive configuration, there is a bug in the 
Macintosh SE ROM floppy disk driver that erroneously de-selects the upper drive in the 
drive select routine, causing it to spin down. If the access was intended to be to the 
upper drive, it must then be re-selected before the access can take place. This makes 
the upper disk drive performance considerably slower than the lower drive. This bug 
will be patched in a future (post 4.1) System file release which will cause it to work 
correctly after booting. 
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#151: System Error 33, “zcbfree has gone negative” 
See also: The Memory Manager 


Written by: Bryan Stearns July 1, 1987 


a 


system 3.2 introduced a new system error, ID=33, generated by the Memory 
Manager when it noticed that a heap had been corrupted in a certain way. 
This error is listed in the file “SysErr.a” as “negZcbFreeErr”. 


The Memory Manager will trigger an “ID=33" system error when, during some operation 
which scans the objects in the heap, it sees that its running count of free bytes (zcbF ree, 
an internal value) has become negative (an impossible feat in normal operation). This is 
nearly always caused by writing zeros past the end of one of the Memory Manager's 
heap blocks (overwriting and corrupting the next block’s header, making it appear to be 
a free block). 


lf you get this error, use a debugger (like Macsbug or TMON) when you attempt to 
reproduce the error, to check the consistency of the heap up to the point where the error 
occurs. You may need to do this repeatedly until you isolate the operation that is 
corrupting the heap. 


Note that although the heap may become corrupted during a system cali, this doesn't 
mean you’ve found a bug in the ROM; your code could be passing incorrect or invalid 
parameters to this or a previous system call, or could have corrupted a data structure 
used by a system call. More debugging is usually in order in this case; tools like 
Discipline (included in TMON; also available from users’ groups and electronic services) 
can help detect invalid parameters in system calls. Also, there is a Macsbug command, 
AH, that can check the consistency of the heap on every system call. See the 
documentation that came with your debugger to see what special features it offers. 


A note about “SysErr.a” 
Technical Support is often asked for an up-to-date list of error codes. In general, this is 
provided in “SysErr.a”, the file of error numbers shipped with the most current version of 


MPW. Admittedly, the documentation value of “SysErr.a” is sometimes low (as in the 
case of negZCBFreeErr), but it may give you a clue as to what the error might mean. 
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#152: Using Laser Prep Routines 


See also: The Printing Manager 
PostScript Language Reference Manuat—Adobe 
Systems 
Technical Note #122: Device-Independent Printing 


Written by: Ginger Jernigan July 1, 1987 





This technical note addresses the issues involved in depending on the 
procedures and constants defined in the Laser Prep dictionary. 





Calling or Modifying Procedures in the Laser Prep Dictionary 


When you are writing an application that uses PostScript heavily, it is very tempting to 
call the procedures already defined in the Laser Prep dictionary, rather than taking up 
the space in the printer's memory with PostScript procedures of your own. Or, if a 
procedure in the dictionary doesn’t do what you need it to do, it is tempting to go in and 
change it to do what you really want. 


Unfortunately, we cannot guarantee that either the name or the function of a particular 
procedure in the dictionary will stay the same when the LaserWriter driver changes. In 
addition, some procedures may become obsolete and go away when the driver 
changes. Since the Laser Prep dictionary is considered part of the source for the 
LaserWriter driver, Apple reserves the right to make any changes to it that are deemed 
necessary. 


Because we cannot guarantee the permanence of the contents of the Laser Prep 
dictionary, relying on its contents can pose a significant compatibility problem. If you rely 
on the procedures defined in the Laser Prep dictionary, your application will have to be 
revised every time Apple releases a new LaserWriter driver. 


If you feel that you absolutely must use or modify procedures in the Laser Prep 
dictionary, you must always check the version that is loaded into the printer before you 
print. This allows your application to take appropriate action if the version of the 
dictionary that has been downloaded to the printer isn't one that you know about. 
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How To Check The Laser Prep Dictionary Version 


To determine the version of Laser Prep that the printer may contain, you have to 
communicate with the printer using the Printer Access Protocol (PAP); you can't just send 
your query through the LaserWriter driver because there is no way to get an answer 
back. The object code and documentation for PAP are available from Apple’s Licensing 
department. 


To determine whether the dictionary has been downloaded and whether it is the right 
one, send the following PostScript code to the printer: 


%!1PS-Adobe-1.2 Query 

$¢Title: Query to establish Laser Prep ProcSet version propriety 
$%?BeginProcSetQuery: AppleDict md xx 

/md where { 

/md get /av get cvi xx eq 

{ (1) }((2) }ifelse) 

{ (0) }ifelse = flush 

%$%?EndProcSetQuery: unknown 

$tEOF 


md is the name of the Apple dictionary and xx is the version number you want. 


Note: /av is a constant in the md dictionary which contains the dictionary’s version 
number. This is the only object in the dictionary whose name and function are 
guaranteed not to change. 


From the printer you will receive a string. If the string returned begins with ‘%%’, it is a 
Status response. You can ignore it and wait for another string. 


lf the response is ‘0’, the dictionary hasn't been downloaded yet; you will need to 
determine how to best handle this situation for your application. 


lf the response is ‘1’, the printer is loaded with the correct version of the dictionary. 


If the response is ‘2’, then the dictionary exists but it isn’t the version you need. In this 
case you need to either let the user know, or proceed in as standard a fashion as 
possible, without calling or modifying routines contained in the Laser Prep dictionary. 


Translating PostScript Files 


Some applications interpret the PostScript files that are generated by the LaserWriter 
driver when the user presses command-F (generates document only) or command-K 
(generates dictionary and document) after clicking on the OK button in the Job dialog. A 
typical application might translate these PostScript files into another page description 
language. 


This kind of application requires intimate knowledge of the contents of the dictionary in 
order to be able to do the translation, because it may have to expand the procedures 
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used to their actual values before it can then translate the PostScript to another 
language. This poses a significant compatibility problem. Since we cannot guarantee 
that the contents of the dictionary will not change, these types of applications will have to 
be revised every time we release a new version of the LaserWriter driver. Also, there is 
no way to know which version of the LaserWriter driver generated the PostScript file the 
application is interpreting. You will have to require that a particular version of the 
LaserWriter driver be used to generate the PostScript files that your application will 
interpret. 


Printer Independence 


Applications that are written to take advantage of the routines in the Laser Prep 
dictionary are, of course, highly device dependent. Being device dependent can 
drastically reduce your chances of being compatible with future printer-type devices. For 
a more detailed discussion of this issue, please refer to Technical Note #122, 
Device-Independent Printing. 
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#153: The New International Utilities and Resources 


See also: The International Utilities (Vol. V)—available from APDA 
The Script Manager (Vol. V)—available from APDA 


Written by: Priscilla Oppenheimer July 1, 1987 


The International Utilities Package and the international resources have 
been changed with System file 4.1 to take advantage of the Script Manager. 
This technical note describes these changes. 


INTL VS. itl 


In the past, there were two INTL resources in the System file, INTL 0 and INTL 1, 
which contained international formatting options. Starting with System 4.1, it10 and 
itll replace INTL 0 and INTL 1. (INTL 0 and INTL 1 are still included with the 

system file so that applications that do a GetResource for them will still find them. 
Doing a GetResource is the only way to access these resources now; the System will 
no longer look at them.) There can now be a set of international resources (it1Ss) for 
each script that is installed. That is, where once there was one resource type (INTL) 
with IDs 0 and 1 there are now many different resource types (it10, it11, it12, itlb, 
itlc, KCHR) with distinct resource IDs for the various countries. The U.S. System file 
uses resource ID 0 for all it 1 resources. 


lf your existing application calls ITUGetInt1 to get the appropriate international 
resource, you will have no problems under System 4.1. If, however, you call 
GetResource On INTL O or INTL 1 and then modify them, and expect that the System 
will use the modified resource, you will no longer work correctly. If your application has 
been released in the past with a modified System file to include your own INTL 0 
and/or INTL 1, you may want to release your application with a modified it 10 and/or 
IEL | 


The international sorting routine 
The international sorting routine is used to handle cases where letters are equal in 
primary ordering but different in secondary ordering (e.g., “a” and “a"). The routine can 


also handle cases where one character sorts as if it were two, or two characters would 
sort as if they were one, or even character reversals. 
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Prior to System 4.1, the international sorting routine was stored starting with the 
localRtn field of INTL 1. As of System 4.1, this routine is now stored in it 12. An 
INTL 2 resource is also included with the international resources, just for consistency 
(the System never uses it). It is exactly the same as it12. 


Writing your own sorting routine can be very dangerous if it is not done correctly. 
Before attempting to do this, we would highly recommend you check with Apple to 
determine if we are already doing one for the language of interest. We plan to do many 
international versions of System file 4.1, and most developers’ needs will be met by 
these. A new policy at Apple will now make it possible to license foreign versions of 
the System file from Software Licensing. Contact Software Licensing at (408) 
973-4667 for more information about this. 


Error in APDA draft of Inside Macintosh Vol. V 


There is an error in the APDA draft of the International Utilities Package chapter of 
Inside Macintosh Vol. V. It says that there is a flag in the Script Manager globals that 
overrides the current font and always uses the INTL 0 and INTL 1 resources. This is 
not true. INTL 0 and 1 have been replaced by it10 and it11, and are not used 
except by applications that explicitly get them by doing a Get Resource. There is a 
relevant Script Manager flag called Int1Force that is correctly but incompletely 
explained in the Script Manager chapter. When Int1Force is false, the resources 
used by the International Utilities are determined by the current script. The script that is 
in use is determined by which font is in use for the port in use. For example, if you 
switch to the Kyoto font, then you will be using the Japanese Script Interface System 
(KanjiTalk). If you do this with Int1Force set to false, then you will use the resources 
that are associated with the Japanese Script Interface System. 


When Int1Force is true, the International Utilities always use the resources that are 
associated with the system script; this is usually Roman. Int1Force is true by default. 
Actually, the Script Manager initialization routine reads the it 1c resource to determine 
what the default is, and Apple plans to release the various international System files 
with this field set to true in the it1c resource. Applications that want to change the 
value of Int1lForce can use the Script Manager call setEnvirons with the 
smiInt 1Force verb. There is a Script Manager call, Int1Script, to find out the current 
value. 


Bug in System file 4.1 version of it11 


There is a bug in the it11 resource in System file version 4.1. The it11 resource 
contains arrays of day and month names, as did the INTL 1 resource. Their formats 
are: 


days ARRAY [{1..7] of STRING[15] 
months ARRAY[i..12] OF STRING[15] 


Every day and month is supposed to be coded as a Pascal string with a maximum of 15 
characters, and the actual length in the first byte of the string. In System 4.0 and 
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System 4.1, the contents of each string is always a Pascal string of length 15, with the 
unused characters set to nulls. In other words, the length byte is set to hex OF. This will 
be fixed in a future release of the System file. If it is currently causing your application 
problems, you can change the lengths with ResEdit, or change them at run time, or use 
your own it11 resource and release your application with an installer script. The 
recommended approach is to wait for a fixed version of the System file from Apple. 
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#154: Displaying Large PICT Files 


See also: QuickDraw 
Technical Note #21—Internal Picture Format 
Technical Note #35—QuickDraw Picture Problem 
Technical Note #88—Signals 


Written by: Rick Blair July 1, 1987 





Now that we have scanners and other massive-picture producing types of 
applications, there is a need to address the problem of how to display a PICT 
format object that is bigger than a current PICT resource is allowed to be. 
Note that this technique applies equally well to Version 1 and Version 2 
(word-opcode) pictures as produced by the Macintosh Il. 





ee 


Future Compatibility 


Think of the handle returned by a GetResource('PICT', ID) as a “handle” in the more 
general sense of being an abstract “tag’—something that the ROM routines can use to 
draw the picture with. Don’t assume that the entire picture has been read into memory or 
that you can directly read any bytes beyond the basic Picture record structure 
(picSize followed by picFrame). Someday we may provide a mechanism for the 
resource to be disk- instead of memory-based. The QuickDraw bottleneck procedures 
will know how to get data from and put data into the pictures in any case. 


Spooling from a PICT file 


In order to display pictures of arbitrary size, your application should be able to import a 
QuickDraw picture from a file of type PICT. This is the file produced by a Save as... 
from MacDraw with the PICT option selected. 


What follows is a small program fragment that demonstrates how to spool in a picture 
from [the data fork of] a PICT file. The picture can be larger than the historical 32K 
resource size. See Technical Note #88 if you are unfamiliar with the signal mechanism. 
We assume that a CatchSignals has been done before GetandDrawPICTFile is 
called. 


CONST 
abortPICT = 128; {Signal error code if DrawPicture aborted for lack 
of space} 
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{the following variable and procedure must be at the main level of the program} 
VAR 
globalRef: INTEGER; 


PROCEDURE GetPICTData(dataPtr: Ptr; byteCount: INTEGER); {replacement 
for the QD bottleneck routine} 


VAR 
err : INTEGER; 
longCount: LONGINT; 
BEGIN 
longCount := byteCount; 
err := FSRead(globalRef, longCount,dataPtr); 
{Can't check for an error because we don't know how to 
handle it} 
END; 


PROCEDURE GetandDrawPICTFile; {procedure to read in a PICT file selected by 


the user} 
VAR 
wher: Point; { where to display dialog } 
reply: SFReply; { reply record } 
myFileTypes: SFTypeList; {more of the Standard File goodies} 
NumFileTypes: INTEGER; 
err: OSErr; 
myProcs: QDProcs; {use CQDProcs for a CGrafPort (a color window) } 
PICTHand: PicHandle; {we need a picture handle for DrawPicture) 
longCount: LONGINT; 
myEOF,filePos: LONGINT; 
myPB: ParamBlockRec; 
BEGIN 


wher.h := 20; 
wher.v := 20; 
NumFileTypes := 1; {Display PICT files} 
myFileTypes{0] := ‘PICT’; 
SFGetFile (wher, '',NIL,NumFileTypes,myFileTypes, NIL, reply); 
IF reply.good THEN BEGIN 
Signal (FSOpen (reply. fname, reply.vrefnum, globalRef)); 


SetStdProcs(myProcs); {use SetStdCProcs for a CGrafPort} 
myWindow*.grafProcs := @myProcs; 
myProcs.getPicProc := @GetPICTData; 


PICTHand := PicHandle (NewHandle(SizeOf(Picture))); {get one 
the size of (size word + frame rectangle) } 


{skip (so to speak) the MacDraw header block} 

Signal (SetFPos (globalRef, fsFromStart,512)); 

Signal (GetEOF (globalRef,myEOF); {get for later double check} 
longCount := SizeOf (Picture); 

{read in the (obsolete) size word and the picture frame} 
Signal (FSRead(globalRef, longCount, Ptr (PICTHand*) )); 


DrawPicture (PICTHand, PICTHand**.picFrame) ; 
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Signal (GetFPos (globalRef,filePos)); 
Signal (FSClose (globalRef) ); 


myWindow*.grafProcs := NIL; 
DisposHandle (Handle (PICTHand) ) ; 


{check for errors. If there wasn't enough room to 
image, DrawPicture will abort so the file mark 
won't be at the end of the file} 
If filePos <> myEOF THEN 
Signal {abortPICT) ; 
END; {IF reply.good} 
END; {GetandDrawPICTFile} 


More on Picture Compatibility 


Many applications already support PICT resources larger than 32K. The 128K ROMs 
(and later) allow pictures as large as memory (or spooling) will accommodate. This was 
made possible by having QuickDraw ignore the size word and simply read the picture 
until the end-of-picture opcode was reached. 


For maximum safety and convenience, let QuickDraw generate and 
interpret your pictures. 


While Apple has provided you with the data formats that allow you to read or write picture 
data directly, we recommend that you always let DrawPicture or OpenPicture and 
ClosePicture process the opcodes. 


One reason to read a picture directly by scanning the opcodes would be to disassemble it 
to, for example, extract a Color QuickDraw pixel map to save off in a private data 
structure. This shouldn't normally be necessary, unless you are working on a CPU other 
than the Macintosh. You wouldn't need to do it, of course, if you were using Color 
QuickDraw. 


If you do look at the picture data be sure and check the version information. You may 
want to put up an alert in your application that indicates to the user when a picture was 
created using a later version of the picture format than your application recognizes, letting 
them know that some elements of the picture cannot be displayed. If the version 
information indicates a QuickDraw picture version later than the one recognized by your 
application, your program should skip over the new opcodes and only attempt to parse 
the ones it knows. 


As with reading picture data directly, it is best to use QuickDraw to create data in the PICT 
format. If you do need to create PICT format data directly, it is essential that you use the 
latest opcode specifications and that you thoroughly test the data produced on both color 
and black and white Macintosh machines. Contact Macintosh Developer Technical 
Support if you are not sure that you have the latest specifications. 


Apple does not guarantee that a picture which wasn’t produced by 
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QuickDraw will work. 
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#155: Handles and Pointers—lIdentity Crisis 


See also: QuickDraw 
Memory Manager 


Written by: Jim Friedlander September 1, 1987 





A handle is a handle and a pointer is a pointer. Applications should avoid 
embedding non-relocatable objects (that the system assumes will never 
move) in handles. 





In order to avoid fragmentation, some applications embed pointers (non-relocatable 
memory manager objects) in handles, so that the handles can be moved around as 
needed. This can cause several problems, especially with the Macintosh Il, and should 
be avoided. 


For example, use of a handle to store a GrafPort can be particularly dangerous. A 
GrafPort must not move between the time that it is opened (OpenPort, NewWindow, 
NewDialog, etc.) and the time that it is closed (ClosePort, DisposeWindow, 
DisposDialog, etc.). Color QuickDraw keeps a list of open ports and pointers to 
them, so, if you create a GrafPort and it moves while still open, color QuickDraw will 
(unknowingly) have a pointer to outer space instead of a pointer to a GrafPort. When 
it needs to use that pointer, it will get hopelessly confused and probably issue a system 
error to let you know. 


As an aside, if you open a port by calling OpenPort Or OpenCPort, you should always 


close the port by calling ClosePort or CloseCPort before calling DisposPtr on the 
port or you will orphan handles (visRgn,clipRgn and more). | 
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#156: Checking for Specific Functionality 

See also: Operating System Utilities 
Assembly Language 
Technical Note #129—SysEnvirons 


Written by: Jim Friedlander September 1, 1987 





This technical note explains how to check at run time to see if specific 
functionality, such as the “new” TextEdit, is present. 





Applications should strive to be compatible across all Macintoshes, but there are times 
when an application must have knowledge about the machine that it is running on. The 
new trap, SysEnvirons, will give an application most of the information that it requires 
(what hardware, what version of system software...). 


Using SysEnvirons 


In most cases, if you examine why you want to test for the existence of a specific trap, 
you will find that there is an alternative method, for example: 


| need to see if the “new” TextEdit calls are available. 


Call SysEnvirons and check to see that SysEnvRec.machineType >= 0 (128K 
ROMs or newer) and that we are running System 4.1 or later (System 4.1 and later 
support the new TextEdit on 128K and greater ROM machines—we can check this by 
just seeing if the SysEnvirons trap exists, if we get an envNotPresent error, we know 
it doesn’t). In Pascal: 


CONST 

CurrentVersion = 1; {Current version of SysEnvirons} 
VAR 

newTextAvail : BOOLEAN; 

theWorld : SysEnvRec; 
BEGIN 


{ 

this code checks to see if System 4.1 or later is running by 
calling SysEnvirons. If SysEnvirons returns an envNotPresent 
error, we know that we are running a system prior to 4.1, so 

we know we don’t have the new TextEdit. If SysEnvirons doesn’t 
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return envNotPresent, we check machine type to make sure we are 
running on 128K ROMs {note that we assume that envMachUnknown has 
at least 128K ROMs when we check to see if machineType >= 0) 

} 


IF SysEnvirons (CurrentVersion,theWorld) = envNotPresent THEN 
newTextAvail:= FALSE 
ELSE 
newTextAvail:= (theWorld.machineType >= 0); 
END; 
In C: 
/* Current version of SysEnvirons */ 
#define CurrentVersion 1 
{ 
Boolean newTextAvail; 
SysEnvRec theWorld; 
/* 
same comment as the Pascal 
x / l 
if (SysEnvirons (CurrentVersion,&theWorld) == envNotPresent) 


newTextAvail = false; 
else 
newTextAvail = (theWorld.machineType >= 0); 


} 
| need to see if PopUpMenuSelect is implemented. 


The same answer as above applies here, since the “new” Menu Manager calls are only 
implemented in System 4.1 on 128K or larger ROM machines (and, as we found above, 
PopUpMenuSelect has the same trap number as _Rename, SO calling 
NGet TrapAddress won't work on 64K ROMs). 


If you find that you need information that is not contained in SysEnvirons, please send 
suggestions for extending it to Macintosh Developer Technical Support at the address 
in Technical Note #0. 


Checking for Specific Functionality 


There are rare times when you may feel that it is necessary to test for specific 
functionality. In order to allow for testing of specific trap functionality, there is an official 
unimplemented trap. This trap ($A89F) is unimplemented on all Macintoshes. To test 
to see if a particular trap that you wish to use is implemented, you can compare its 
address with the address of the unimplemented trap. Here are two fragments that show 
how to check to see if Shutdown is implemented. First, Pascal: 


CONST 
ShutDownTrapNum = $95;{trap number of Shutdown} 
UniImp1TrapNum = $9F;{trap number of “unimplemented trap”} 
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VAR 
ShutdownIsImplemented + BOOLEAN; {is Shutdown implemented} 


BEGIN 
{Is Shutdown implemented? } 
ShutdownIsImplemented := 


NGet TrapAddress (ShutDownTrapNum, ToolTrap) <> 
NGet TrapAddress (UnImp1TrapNum, ToolTrap) ; 


END; 
Here's a C fragment: 


/*trap number of Shutdown*/ 


#define ShutDownTrapNum 0x95 
/*trap number of “unimplemented trap”*/ 
#define Unimp1lTrapNum Ox9F 


{ 
Boolean ShutdownIsImplemented; 


/*Is Shutdown implemented?*/ 

ShutdownIsimplemented = 
NGet TrapAddress (ShutDownTrapNum,ToolTrap) != 
NGet TrapAddress (UniImp1TrapNum, ToolTrap) ; 


} 
NGet TrapAddress is used because it ensures that you will get the correct trap in case 
there is a ToolTrap and an OSTrap with the same number. Please note that calling 
NGet TrapAddress does not cause compatibility problems with 64K ROMS. When run 
on those ROMs, it just becomes a Get TrapAddress call. You have to be careful on 
64K ROMs — you can't test for_PopUpMenuSelect ($A80B), for example, because it 
has the same trap number as_Rename($A00B). The 64K ROM didn’t really differentiate 
between ToolTraps and OSTraps (there was no overlap in trap numbers). So, if you 


wanted to test for PopUpMenuSelect, you would need to first check to make sure you 
weren't running on 64K ROMs (see below). 


You can get the trap number of the trap you wish to test for from Inside Macintosh 
(Appendix C of Volumes I-Ill and Appendix B of Volume IV). You can tell if the trap is an 
OSTrap Or a Tool Trap by checking to see if bit 11 in the trap word is set, that is, traps 
like $A8xx (or $A9xx OF $AAxx) that have the “8” component set, are ToolTraps and 
traps that don’t (SAOxx) are OSTraps. The trap number that you pass to 
NGet TrapAddress for ToolTraps is the low 9 bits of the trap word (the trap number for 
_PopUpMenuSelect [$A80B] iS $00B) . The trap number that you pass to 
NGet TrapAddress for OSTraps is the low 8 bits of the trap word (the trap number for 
_MoveHHi [$A064] is $064). 


Shutdown ($A895) is just an example of a trap that we might need to check before 
calling. Most applications won't call ShutDown, SO this is just an example of how to do 
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the testing. 
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#157: Problem with GetVInfo 
See also: _ File Manager 


Written by: Jim Friedlander -= September 1, 1987 


The high-level call Get VInfo (and its low-level counterpart PBGet VInfo) 
may return inaccurate results for freeBytes when running HFS. 


The high-level File Manager call Get VInfo returns the number of free bytes on a 
volume as one of its parameters. Since Get VInfo is really only glue that fills in a 
parameter block for you and then calls PBGet VInfo, the values returned from it are 
subject to the limitations (imposed for MFS) discussed in the File Manager chapter of 
Inside Macintosh Volume IV (p. 130): “Warning: IOVNmA1Blks and iovFrBlks, 
which are actually unsigned integers, are clipped to 31744 ($7C00) regardless of the 
size of the volume.” 


The value that Get VInfo returns in freeBytes (ioVFrBlks * ioVNmA1B1ks) will 
thus be less than or equal to the actual number of free bytes on a volume. This isn't 
catastrophic, but can be highly inconvenient if you really need to know how much free 
space is on a given volume. 


Note: ioVNmA1Blks returned from PB(H]GetViInfo does not reflect the actual total 
number of blocks on an HFS disk, but rather only the blocks that are “available” for 
program use {it doesn’t count blocks used for catalog information). 


Here are two functions (one in MPW Pascal, one in MPW C} that return the actual 
number of free bytes on a volume, regardless of File System (if MFS is running, the 
PBHGet ViInfo Call will actually generate a PBGet VInfo Call which will return the proper 
values for MFS volumes): 


In MPW Pascal: 


FUNCTION FreeSpaceOnVol (vRef:Integer; VAR freeBytes:Longint): OSErr; 


TYPE 
{we need this to convert an unsigned integer to an unsigned 
lengint } 
TwolntsMakesALong = RECORD 
CASE Integer OF 
1: (long: LongInt); 
2: (ints: ARRAY [0..1] OF Integer); 
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END; {TwoIntsMakesALong} 


Technical Note #157 page 2 of2 Problem with GetVinfo 


VAR 


HPB : HParamBlockRec; 
convert : TwoIntsMakesALong; 
err e OSErr; 


BEGIN {FreeSpaceOnvol } 
WITH HPB DO BEGIN {set up parameter block for the PBGetVInfo call} 


ioNamePtr := NIL; {we don’t care about the name} 
iovRefNum := vRef; {this was passed in as a parameter} 
ioVolindex := 0; {use ioVRefNum only} 

END; {WITH } 

err := PBHGetVinfo (@HPB, false); 

FreeSpaceOnvVol:= err; {return error from HGetViInfo} 


{ 
This next section needs some explanation. ioVFrBlk is an unsigned 
integer. If we were to assign it(or coerce it) to a longint, it would get 
sign extended by MPW Pascal and would thus be negative. Since we don’t 
want that, we use a variant record that maps two integers into the space 
of one longint. The high word (convert.ints[0]) is cleared in the first 
line, then the low word is assigned the value of HPB.ioVFrBlk. The 
resulting longint (convert.long) is now a correctly signed (positive) long 
integer representing the number of free blocks. NOTE: this is only 
necessary if the number of free blocks on a disk exceeds 32767 (S7FFF). 
} 
IF err = 0 THEN BEGIN 

convert.ints[0] := 0; 

convert.ints{[1] := HPB.ioVFrBlk; 

freeBytes:= convert.long * HPB.ioVA1B1kSiz; 

END ELSE {PBHGetVInfo failed} 

freeBytes:= 0; {return this if the routine failed} 

END; {FreeSpaceOnVol } 


In MPW C: 


OSErr freeSpaceOnVol (vRef, pfreeBytes) 
short int vRef; 
unsigned long int *pfreeBytes; /* C does this correctly!! */ 


{ /* freeSpaceOnVol */ 
HVolumeParam HPB; 
OSErr err; 


HPB.ioNamePtr = OL; /* we don’t care about the name */ 
HPB.ioVRefNum = vRef; /* this was passed in as a parameter */ 
HPB.ioVoliIndex = 0; /* use ioVRefNum only */ 


err = PBHGetVInfo (&HPB, false); 
if (err == noErr) 
*pfreeBytes = (unsigned long int)HPB.ioVFrBlk * 
HPB.ioVA1B1kSiz; 


else 
*pfreeBytes = OL; /* return this if the routine failed */ 
return (err) ; /* function result */ 
} /* freeSpaceOnVol */ 
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#158: Frequently Asked MultiFinder Questions 


See also: Technical Note #129—SysEnvirons 
Technical Note #156—Checking For Specific Functionality 


Written by: Jim Friedlander September 1, 1987 


This technical note provides answers to some of the more frequently asked 
questions about beta version 1.0B5 of the MultiFinder. The development 
name for MultiFinder was Juggler, so the term “juggle” is used in this 
technical note to denote a context switch. For more information, please 
order the MultiFinder Developer’s Package from APDA. 


How can I tell if WaitNextEvent is implemented? 


Most applications should not need to tell if MultiFinder is running. Most of the time, the 
application really needs to know something like: “How can | tell if WaitNextEvent is 
implemented?” Here’s a Pascal fragment that demonstrates how to check to see if 
WaitNextEvent is implemented (the next version of SysEnvirons will most likely 
contain checks for MultiFinder): 


CONST | 
WNETrapNum = $60;{trap number of WaitNextEvent} 
UniImplTrapNum = $9F; {trap number of "unimplemented trap"™} 
VAR 
WNEIsImplemented : BOOLEAN; {is WaitNextEvent implemented} 
theWorld : SysEnvRec; 
err : OSErr; 
BEGIN 


we need to call SysEnvirons to make sure that WNEIsImplemented. If we are running on 
64K ROMS AND RAM HFS is running (trap $A060) then GetTrapAddress ($60) will return a 

value different from the unimplemented trap since trap 60 is implemented for HFS and 
the 64K ROM version of GetTrapAddress doesn’t differentiate between OS and Tool Traps 


err:= SysEnvirons(1,theWorld);{we have glue, so machineType will always be filled in!} 
{Is WaitNextEvent implemented?} 
WNEIsImplemented:= (theWorld.machineType >= 0) & 

(NGetTrapAddress( WNETrapNum,ToolTrap) <> 

NGetTrapAddress (UnImplTrap, ToolTrap) ); 
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{Main Event Loop} 
IF WNEIsImplemented THEN 
WaitNextEvent (...) 


ELSE BEGIN 
SystemTask; {for drivers, since we’re calling GNE not WNE} 
GetNextEvent (...) 7 
END; {ELSE} 
END; 


Here’s a C fragment: 


/*trap number of WaitNextEvent*/ 
#define WNETrapNum 0x60 

/*trap number of "unimplemented trap"*/ 
#define UnImplTrapNum Ox9F 


{ 


Boolean WNEIsImplemented; 
OSErr err; /* for SysEnvirons */ 
SysEnvRec theWorld; 
/* 
Same comment as in the above Pascal code 
“7 


err = SysEnvirons(1,&theWorld); /* we have the glue, so machineType will always be 
filled in! */ 


/*Is WaitNextEvent implemented?*/ 

WNEIsImplemented = (theWorld.machineType >= 0) && 
(NGetTrapAddress{ WNETrapNum,ToolTrap) != 
NGet TrapAddress (UnImplTrap, ToolTrap) ) 3 


/*Main Event Loop*/ 

if (WNEIsImplemented) 
WaitNextEvent (...) 3 

else 

{ 
SystemTask(); /* for drivers */ 
Get NextEvent (...) ? 

} /* else */ 


This code compares the trap for WNE with the unimplemented trap. NGetTrapAddress 
is used because it adds a little precision to the process. Please note that calling 
NGet TrapAddress does not cause compatibility problems with 64K ROMS. When run 
on those ROMs, it just becomes a Get TrapAddress Call. Note: WaitNextEvent does 
not conflict with any OS Trap, so the above test is valid on 64K ROMs. 


Note: Testing to see if WaitNextEvent is implemented is not the same as testing to 
see whether MultiFinder is running. Future systems may include WaitNextEvent 
whether or not MultiFinder is running. 


How can | tell if the MultiFinder Temporary Memory Allocation 
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calls are implemented? 


Uy aa that’s used to determine this is similar to the above technique. In 
ascal: 
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FUNCTION TempMemCallsAvail: BOOLEAN; 


TYPE 
LongPtr = “Longint; 
CONST 
SwitchPtr = $282; {low-memory long-word global for switcher} 
JugglDispatch = $8F; {trap number of Juggler dispatch trap -- ToolTrap} 
UnimplTrap = $9F; {trap number of unimplemented trap ~~ ToolTrap} 
VAR 
switchP : LongPtr; 
theWorld : SysEnvRec; 
JugglDispIsImplemented : BOOLEAN; 
BEGIN {JugglerLives} 


switchP := LongPtr(SwitchPtr); 
err:= SysEnvirons({1,theWorld);{we have glue, so machineType will always be filled in!} 


The above is not strictly necessary though JugglDispatch won’t be implemented on 64K 
ROMs. SysEnvirons is called simply for consistency with the above check for 
WaitNextEvent. 


JugglDispIsImplemented:= (theWorld.machineType >= 0) & 
(NGetTrapAddress (JugglDispatch,ToolTrap) <> 
NGet TrapAddress (UnImplTrap, ToolTrap) }; 


JugglerLives := JugglDispIsImplemented & ((switchP* = 0) | {switchP* = - 1)) 
END; {TempMemCallisAvail)} 
In C: 
#define SwitchPtr (long *) (0x282) 
#define JuggliDispatch Ox8f 
#define UnImp1Trap Ox9f 
Boolean TempMemCallsAvail {) 


{ /*TempMemCallsAvail*/ 


Boolean JugglDispIsImplemented; 
OSErr err; /* for SysEnvirons */ 
SysEnvRec theWorld; 


err = SysEnvirons({1,étheWorld); /* we have glue, so machineType will always be filled 
int */ 
{x 
Same comment as in the above Pascal code 
*/ 


JugglDispIsImplemented = (theWorld.machineType >= 0) && 
(NGetTrapAddress (JugglDispatch,ToolTrap) != 
NGet TrapAddress (UnImplTrap, ToolTrap) ); 


return( JugglDispIsImplemented & ({*SwitchPtr==0) 1] (*SwitchPtr == -1))); 
} /*TempMemCallsAvail*/ 


This routine checks to see if the long word in $282 is —1 (Switcher has not run) or 0 
(Switcher has run and quit). If one of these is true, it then compares the MultiFinder 
dispatch trap with the unimplemented trap. If the MultiFinder dispatch trap is 
implemented, then the MultiFinder Temporary Memory Calls exist. If the long word in 
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$282 is not equal to either —1 or 0, then Switcher is active, so MultiFinder isn't. 


How can I tell if my application is running in the background? 


To run in the background under MultiFinder, an application must have set the 
canBackground bit (bit 12 of the first word) in the SIZE resource. In addition, the 
accept SuspendResumeEvents bit (bit 14) should be set. 


An application can tell if it is running in the background if it has received a SUSPEND 
event but not a RESUME event. 


When exactly does juggling take place? 


Juggling takes place at WaitNextEvent/GetNextEvent/EventAvail time. If you 
have the accept SuspendResumeEvents bit set in the SIZE resource, you will receive 
SUSPEND/RESUME events. When you get a SUSPEND event (or, when you call 
EventAvail and a SUSPEND event has been posted), you will be juggled out the 
next time that you call WWE/GNE/EventAvail. When you receive a SUSPEND event, 
you are going to be juggled, so don’t do anything to try to retain control (such as calling 


ModalDialog). 


Speaking of ModalDialog, MultiFinder will not SUSPEND your application when the 
frontmost window is a modal dialog, though background tasks will continue to get time. 


Can I disable SUSPEND/RESUME events by passing the 
appropriate event mask to WNE/GNE/EventAvail? : 


SUSPEND/RESUME events are not queued, so be careful when masking out 
app4Evts. You will still get the event, all that will happen if you mask out app4Evts is 
that your application won't know when it is going to be juggled out (your application will 
still be juggled out when you call WNE/GNE/EventAvail). If your application sets a 
boolean to tell whether or not it’s in the foreground or the background, you definitely 


don’t want to mask out app4Evts. 


Should my application use WaitNextEvent? 


Yes, this will enable background tasks to get as much time as possible. All user events 
that your program needs to handle will be passed to your application as quickly as 
possible. Applications that run in the background should try to be as friendly as 
possible. It’s best to do things a small chunk at a time so as to give maximum time to 
the foreground application. “Cooperative multi-tasking” requires cooperation! 


lf your application calls WaitNextEvent, it shouldn't call SystemTask. 
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Is there anything else that I can do to be MultiFinder friendly? 


It is very important that you save the positions of windows that you open, so that the 
next time the user launches your application, the windows will go where they had them 
last. This greatly enhances the usability of MultiFinder. With data files, the window 
positions can be stored in either the resource or the data fork. 


If you have windows that aren’t data windows (i.e. separate files), you can store 
information about their positions in one of two ways: in a separate configuration file or 
in a resource in your application. Using a separate configuration file is necessary if 
your application is shareable on AppleShare, since resource forks are not. The 
configuration file should be put in the folder that contains the currently open system 
folder (this is guaranteed to be a local, non-shared volume as opposed to a server 
volume). The vRefNum/WDRefNum of this folder can be obtained by calling 
SysEnvirons (SysEnvRec.sysVRefNun). 


Can I use a debugger with MultiFinder? 


Yes, MacsBug will ioad normally, since it is loaded well before MultiFinder. Since 
TMON is currently installed as a startup application, you should Set Startup to it, then 
launch MultiFinder manually (by holding down Option-Command while double-clicking 
the MultiFinder icon) or use a program that will run multiple startup applications (such 
as Sequencer), making sure that TMON is run before MultiFinder. If you try to run 
TMON after MultiFinder has been installed, a system crash will result. The latest 
version of TMON (2.8) has an INIT that loads it before MultiFinder is present. 


it is necessary to check CurApName ($910) when you first enter a debugger (TMON 
users can anchor a window to $910) to see which layer (whose code, which 
low-memory globals and so on) is currently executing, especially if you entered the 
debugger by pressing the interrupt button. 

What happened to animated icons under MultiFinder? 

Finder 6.0 no longer uses the mask that you supply in an ICN# to “punch a hole” in the 


desktop. Instead, it uses a default mask that consists of a solid black copy of the icon 
with no holes; see Technical Note #147 for details. 


How can | ensure maximal compatibility with MultiFinder? 


if you follow the guidelines presented in the MultiFinder Developer's Package you will 
stand a very good chance of being fully compatible with MultiFinder. 


Technical Note #158 page 7 of5 Frequently Asked MultiFinder Questions 


Macintosh Technical Notes C3 


#159: Hard Disk Hacking 


See also: Technical Note #96—SCSI Bugs 
Technical Note #134—Hard Disk Medic 
Device Manager 


Written by: Bo3b Johnson September 1, 1987 


Sethi 


For those of a technical bent with some extra time, you can build your own 
hard disk system from a cheap SCS! drive and a driver that you write. This is 
not a project for those short on time, so beware. 


We often get questions regarding the feasibility of connecting a ‘generic’ SCSI drive to 
the Macintosh, usually the Macintosh Il. It is possible to use a standard drive, but it is 
important to be aware that there is a reason why a fully assembled drive costs more. 
When buying a hard disk you have two choices: 

1) buy a fully assembled drive, formatting and driver software included 

2) buy the pieces necessary to assemble your own: the drive itself, power supply if 
needed, cables, and development system to write a driver and formatter. 
The second choice will often appear to be cheaper, since you don’t have to pay for a 
fancy case with a fancy label. However, you are also missing the chance to pay for some 
fancy software that took some fancy amounts of time to write. 


Do not underestimate the difficulty of building your own hard disk. SCSI drives are only 
partially standardized so a driver written for one drive will probably not work (at least not 
well) on another drive. All drives come with a formatting utility that also contains a driver 
for reading and writing sectors to the disk. For example, the Apple drives come with a 
program called HD SC Setup. Most third-party drives have a similar utility that is specific 
to their drive. The formatting operation varies widely depending on the drive, and the 
driver also may have to know about specific timing problems with a given drive. HD SC 
Setup can only support the drives which we produce. 


if you decide that you want to hack together your own drive, you will need to write this 
formatter/driver program. It is non-trivial, and this is part of what you pay for when you 
buy an off-the-shelf drive. If you have the time, you may Save some money. If you are 
writing your own formatter/driver program we can help you with problems you run into, 
but you must be familiar with SCSI terminology, the SCSI Manager, and be able to use 
an assembly level debugger like Macsbug or TMon. You may run into timing difficulties 
that require the use of a logic analyzer or SCSI analyzer to resolve. 
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This may sound like it is hard to write your own driver. Itis. This may sound like we are 
trying to scare you off from writing your own driver. We are. 
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#160: Key Mapping 
see also: The Script Manager 


Written by: Cameron Birse September 1, 1987 


This technical note describes the key code mapping scheme used in the 
Macintosh SE, Macintosh Il, and System file 4.1 and later. It also provides a 
“safe” method for remapping keyboards. 


The keystroke mapping mechanism has been changed for the Macintosh SE, the 
Macintosh ll, and version 4.1 of the System file. Originally, a keystroke caused an 
interrupt, and the interrupt handler dispatched the keycode to a translation routine 
pointed to by a low memory pointer (Key1Trans Of Key2Trans). This routine was 
installed at boot time by the System, and was generally replaced entirely or in part for 
remapping the keyboard. When the keycode was mapped, it was returned to the 
interrupt handler, and the handler then posted the event. The translation routine and 
the key map were both contained in the System file resources INIT O and 1. 


In the new System file, the low-memory pointers are still there and are still called by the 
Macintosh Plus, but are not called by ADB systems. They are preserved so that 
applications that call them will still be able to use them to translate keycodes. They now 
point to a routine that implements the new System mechanism. In this new mechanism, 
the keystroke causes an interrupt, and the interrupt handler maps the raw keycode to a 
“virtual” keycode, which is then sent to a trap called KeyTrans. This routine maps the 
virtual keycode to an ASCII value, and returns that to the handler, which posts the 
event. 


With the advent of new keyboards, a mechanism was needed to map the different raw 
keycodes to a standard virtual keycode that could be mapped to the ASCII and special 
character sets. The mapping from raw to virtual keycodes is done for keyboard 
hardware independence. The raw mapping routine uses a table resident in the System 
resource KMAP. Basically, the raw keycode is used to index into the table in KMAP. 
The value at the indexed location in KMAP is what is returned as the virtual keycode. 
The format of the KMAP resource is described below. 


The mapping of the virtual keycode to the ASCII character is done by a new trap in the 
Macintosh SE and Macintosh Il ROMs, and in System 4.1 (and later) for the Macintosh 
Plus. The new trap is called KeyTrans (not to be confused with the Key1Trans or 
Key2Trans pointers), and it maps the virtual keycode to an ASCI! keycode (based on 
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modifiers, if any) using tables that reside in the System resource KCHR. The format of 
the KCHR resource is also described below. | 


FUNCTION KeyTrans (transData:Ptr;keycode:Integer;VAR state:Longint) : LONGINT 


The transData parameter is a pointer to the KCHR image in memory. The keycode 
parameter is an integer comprised of the modifier flags in bits 8-15, an up/down stroke 
flag in bit 7 (1=up), and the virtual key code in bits 6-0. The state parameter is a value 
internal to KeyTrans which should be preserved across calls if dead keys are desired. 
It is dependent on the KCHR information, so if the KCHR is changed, state should be 
reset to 0. 


The LONGINT returned is actually two 16-bit characters to be posted as events (usually 
the high byte of each is 0), high word first. A returned value of 0 in either word should 
not be posted. Do not depend on which word the character will end up in. If both words 
are valid, then the hi word should be posted first. 


In the Macintosh SE and Macintosh II, the KMAP and KCHR resources are in ROM. In 
the Macintosh Plus, the System uses a KCHR resource in the System file. In order to 
remap the keyboard, you must supply a KCHR resource and have the System use it. In 
addition to the KCHR resource, there is an associated SICN resource. The SICN 
resource provides a graphic representation of the current keyboard mapping. For 
example, the French keyboard layout has a SICN of a French flag to designate that 
particular map is currently active. The SICN resource should be some representation of 
your particular remap, and its ID# must be the same as the KCHR’s. The KCHR 
resource must be named appropriately, as there will be a Control Panel option that will 
allow the user to choose the appropriate map. 


Remapping the keyboard 


Remapping the keyboard can be done two ways: either at boot time, or from within an 
application. Remapping from within an application can be made permanent (until the 
next boot), or only for the life of the application. The remapping is accomplished by 
modifying a KCHR resource, and telling the System to use the new KCHR. The KCHR 
must have an ID number in the range of the appropriate script, and must have an 
associated SICN resource with the same ID number. The Roman script, for example, 
uses the range 0 to 16383, and the standard KCHR IDs for each country are the same 
as the country code (US = 0, French = 1, German = 2, italian = 3, etc.). Alternative 
Roman keyboards should have numbers somewhere in the script range, e.g. “Dvorak” 
at ID 500. 


To remap the keyboard at boot time, there must be a modified KCHR resource in 
the System file with an ID in the range of the appropriate script. In addition to the KCHR 
resource, there must be an associated SICN resource. To make the System use the 
modified KCHR at boot time, you must change the entries in the itlb resource in the 
System file to reflect the ID of the modified KCHR, and SICN resources. The itlb 
resource format is described below. 
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Apple’s System Software Licensing policy forbids shipping a modified System file; we 
suggest an installer program that the user can execute to perform the installation of the 
new resources. The installer program should assign the new resources their IDs based 
on what is currently in the System file so there won't be a conflict. 


itib resource format 


type ‘itlb’ { 


unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
}; 


integer; 
integer; 
integer; 
integer; 
integer; 
integer; 
integer; 
integer; 
integer; 
integer; 


itib © International Script Bundle---------------- */ 
/* itl0 id number */ 
/* itll id number x / 
/* itl2 id number * / 
/* reserved x / 
/* reserved */ 
/* reserved */ 
/* language code {e.g. langFrench) */ 
/* number/date codes */ 
/* KCHR id number */ 
/* SICN id number */ 


To remap the keyboard after boot, you need a KCHR (and SICN) in your 
application or in the System file (with an ID in the range of the appropriate script), and 
you need to use the following calls to the Script Manager (the Script Manager is included 
in System 4.1 and later). The first call to SetScript sets the Script Manager’s global 
variable for the KCHR resource ID, and the second call to SetScript sets the Script 
Manager's global variable for the SICN resource iD. When these calls are completed, the 
call to keyScript will load the resources, and set up the System to use them. 


const 


DvorakID = 500; 


var 


myErr: 


begin 


Oserr; 


myErr := SetScript(smRoman, smScriptKeys, DvorakID); 
myErr := SetScript(smRoman, smScriptIcon, DvorakID); 


KeyScript (smRoman) ; 
end; 


end. 


KCHR resource format 


Version 


Indexes (to character table) 


Count of character table arrays 


Character table arrays 
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2 bytes (integer) 
256 bytes (array of bytes) 
2 bytes (integer) 


128 bytes each {array of char) 


Key Mapping 


Count of DeadKey Records 2 bytes (integer) 


DeadKey record variable length (array) 
table number 1 byte 
virtual keycode 1 byte 
count of Completor Records 2 bytes (integer) 
Completor Character 1 byte (char) 
Substituting Character 1 byte (char) 
no match character 1 byte (char) 
extra room for 16 bit Character Codes 1 byte (char) 


The KCHR resource consists of a 2 byte version number followed by a 256 byte modifier 
table, mapping all 256 possible modifier states to a table number. This is followed by a 2 
byte count of tables, which is, in turn, followed by that many 128 byte ASCII tables. The 
ASCII table maps the virtual keycode to an ASCII value; 0 signifies a dead key, in this 
case the dead key table must be searched. 


The dead key table is comprised of a count of dead key records (2 bytes), and that many 
dead key records. A dead key record consists of a one byte table number, a one byte 
virtual keycode (without up/down bit), a completor table, and a 2 byte no-match 
character. 


When KeyTrans searches the dead key records, it checks for a match with the table 
number and the keycode. If there is no match, it is no a dead key, and a zero is returned. 
if there is a match, it is recorded in the state variable. If the previous key was a dead key, 
the completor table will be searched. The completor table is comprised of a count of 
completor records, followed by that number of completor records. 


A completor record is simply a substitution list for ASCII characters. If the ASCII character 
matches the first byte in the completor record, the second byte will be substituted for it. 
When there is no substitution to be made, the original ASCII character is preceded by the 
no match character found at the at the end of the dead key record. 


KMAP Resource format 


ID 2 bytes (integer) 
Version 2 bytes (integer) 
Raw to virtual keycode map 128 bytes (array) 
Count of Exception arrays 2 bytes (integer) 
Exception arrays (array) 
raw keycode 1 byte 
noXor, Xor 1 bit (boolean) 
fill bits 3 bits 
ADB opcode 4 bits (bitstring) 
data string variable length (pascal string) 


The KMAP resource starts with a two byte ID, followed by a two byte version number. 
This is followed by the 128 byte keycode mapping table, described above in this 
technical note. The table is followed by a list of exceptions. 
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The 128 byte table is simply a one-to-one mapping of real keycodes to virtual keycodes, 
the first byte is the virtual keycode for $00, the second for $01, etc. The high bit of the 
virtual keycode signals an exception entry in the exception list. 


The exception list is used to enable the device driver to initiate communication with the 
device, usually to perform a state change. The exception list begins with a two byte 
record count followed by that many records. The format of the exception record is shown 
above. The raw keycode is the keycode as generated by the device. The XOR bit 
informs the driver to invert the state of the key instead of using the state provided by the 
hardware. This can be used to provide keys that lock in software. The ADB opcode is 
described in the Inside Macintosh chapter on the Apple DeskTop Bus in Volume V. 
Finally the data string is a Pascal string that is passed to the ADBOp trap. 
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#161: When to Call PrOpen and PrClose 


See also: Printing Manager 
Technical Note #122—Device-Independent Printing 


Written by: Ginger Jernigan September 1, 1987 





—— 


At one time we recommended that developers call Propen at the beginning of their 
application and PrClose at the end before returning to the Finder. This was in the 
ancient past when there was only one printer driver that an application had to deal with. 


As more printer drivers became available, it became important for an application to be 
more careful about when it opened the printer driver. The user could just bring up the 
Chooser at any time and instantly change the current printer without the application ever 
knowing. If the application followed the old philosophy of opening the printer driver at 
initialization time and the user chose a different printer while within the application, the 
next time the user printed, they would get an error because the wrong driver was open 
and the Printing Manager couldn't find the resources it needed. 


The Current Recommendation 


We currently recommend that applications open and close the printer driver each time the 
application uses the Printing Manager. For example, when the application calls 
PrSt1Dialog, the call is bracketed by Propen and PrClose, like this: 


PrOpen; {open the driver} 
IF PrError = noerr 
THEN 
BEGIN {check the error} 
temp := PrValidate (PrintStuff); 
temp := PrStlDialog(PrintStuff); {call the dialog} 
IF PrError <> noerr THEN MyPrErrAlertProc 
ELSE {set my page rectangle} 
theWorld := PrintStuff**.prinfoPT.rpage; 
END 
ELSE 
MyPrErrAlertProc; 
PrClose; {close it} 


The same is true of the print loop: 
GetPort (myport); {save my port for later} 
PrOpen; {open up printer resource file} 


IF PrError = noerr 
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THEN 
BEGIN 
temp := PrValidate(PrintStuff); (Validate the record} 


myPrPort := PrOpenDoc (prRecHdl, NIL, NIL); { open printing grafPort } 
FOR pg := 1 TO myPgCount DO {page loop: ALL pages of document} 
IF PrError = noErr 
THEN 
BEGIN 
PrOpenPage (myPrPort, NIL); {start new page} 
IF PrError = noErr 
THEN MyDrawingProc (pg); {draw page with QuickDraw} 
PrClosePage (myPrPort) ; {end current page} 
END; 
PrCloseDoc (myPrPort) ; 
IF prRecHd1l**.prdob.bJDocLoop = bSpoolLoop AND PrError = noErr 


THEN 

BEGIN 
MySwapOutProc; {Swap out code and data} 
PrPicFile (prRecHdl, NIL,NIL,NIL,myStRec); {print spooled document } 
END; 

IF PrError <> noErr THEN MyPrErrAlertProc; {report any errors} 

END; 

PrClose; 


SetPort (myport); {set my port back} 


Before the application starts the print loop it calls Propen, and after it has finished it calls 
PrClose. This will insure that the current driver will always be available. 
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#162: MPW 2.0 Pascal Compiler Bug 
Written by: Jim Friedlander September 1, 1987 


mpm n m o 


The MPW 2.0 Pascal compiler has a bug that can cause either a compile 
time error or bad code generation. This technical note will discuss the bug 
and workarounds. A new Pascal compiler (2.0.1) will be made available to 
everyone who purchased MPW 2.0 Pascal from APDA at no charge. 


The Problem 


The bug occurs under the following very well defined set of circumstances, when 
accessing an element of an array from a local procedure: 


¢ The array must be declared in a UNIT as a global variable (either in 
IMPLEMENTATION Of INTERFACE). If the array is declared as a global in your 
main program, this problem will not occur. 

e The base type of the array must be a byte (8.g. array[m..n] of 
SignedByte Ofarray[m..n] of myScalarType). 

e The array must not be packed. 

e The array must not be zero-based (e.g. array[0..n]} would not exhibit the 
problem. 

e Range checking must be off ({ $R-}). 

e The index expression must be a simple variable (on either the left or the right 
side). Eithera[i]:= b Orb:= a[i} will cause the problem, whereas 
a[itj]:= b will not. 

e The index must be local to a procedure (including parameters). The calling 
procedure can be located anywhere. 

e The index must be referenced more than once (so that a register is allocated 
for it). 


All of the above conditions must be met or the problem will not occur—this may seem 
unlikely, but the above conditions are fairly typical for a large application that is divided 
into UNITS. 


The Symptoms 


The above set of circumstances can cause the compiler to generate either a compiler 
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error: 


### Code Generator Fatal Error 

### Register 0..3 

### Within X (Error 2001): Expression too complicated, code generator ran 
out of registers ### 

### IC = 78, IN = 0:145 


or bad code. The first case is very easy to find, the latter case is not. You should 
examine your source code carefully to see if your code uses an array in the manner 
outlined above, and, if so, use one of the workarounds listed below. 


An Example 
The following procedure references a global array that is declared in a UNIT as follows: 


CONST 
ArrayBase = 11; {some non-zero number} 
ArrayEnd = 222; 


VAR 
UArr: array [ArrayBase..ArrayEnd] of SignedByte; 


Here’s a simple procedure that will cause bad code to be generated: 
PROCEDURE doTheBug; 


VAR 
i,j,k: integer; 


BEGIN {doTheBug} 
Lea} 


i:= j+k; {force register to be used for i} 
Ferid 

i:= 12; {second element of UArr} 

UArr[i]:= 6; {UArr is a global in a UNIT} 


END; {doTheBug} 


The last two lines of doTheBug generate the following problematical code: 


; i:= 12; 


MOVEQ #$0C,D7 move index(i) into D7 


“e 


: UArr[i]:= 6; 

MOVE.L D7,D0 > move index into DO 

SUB.W #5000B, D0 ; adjust to base of array 

LEA SFF2C (A5) , AO ; get address of global array 

MOVE .B #506,$00 (A0,D7.W) ; mistakenly uses D7 instead of DO 


As you can see from the above, the value 6 is being stored in a location that is i bytes, 
instead of i-ArrayBase bytes, from the start of the array. 
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The Workarounds 
There are several workarounds: 


e Use only zero-based arrays. This has the added benefit that it generates faster 
code. 

e Use an index expression that is computed at run-time (instead of a[i]:= b use 
a[i+j]:= b, where j = 0) 

¢ Refer to @i in the same procedure (this forces i out of a register). 

e Get the new 2.0.1 Pascal compiler from APDA (no charge update). 
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#163: Adding Color With CopyBits 
See also: Color QuickDraw 


Written by: Chris Derossi November 2, 1987 





Inside Macintosh volume V states that the foreground and background colors 
are applied to an image during a CopyBits Or CopyMask Call. Accidental use 
of this feature can create bizarre coloring effects. This technical note explains 
what happens, how to avoid problems, and how to use it. 





What Happens 


Color QuickDraw has a feature that will allow you to convert a monochrome image to a 
color image. During a CopyBits Oor CopyMask Call, if the foreground and background 
colors are not black and white, respectively, Color QuickDraw performs the following 
operation on every pixel being copied: 


NOTE: color table index = pixel value 


s = color table index of source pixel 
= color table index of foreground color 


fg 
bg = color table index of background color 


ColoredPixelValue = (NOT(s) AND bg) OR (s AND fg) 


If your source image contains only black and white pixels, then all black pixels would 
become the foreground color and all white pixels would become the background color. 
This is because the color table index for white is all zeros and the color table index for 
black is all ones. 


For example, suppose your source image was a 4-bit deep color PixMap. Then the color 
table index for white (in binary) is 0000 and the index for black is 1111. And let’s 
suppose that your foreground color is green with an index of 1101 while your 
background color is red with an index of 0011. Then for the black pixels, the above 
procedure produces: 


NOT(1111) AND 0011) OR (1111 AND 1101) 
0000 AND 0011) OR (1111 AND 1101) 


ColoredPixelValue 


= 4 
1101 = ( 
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And the operation on the white pixels yields: 


ColoredPixelValue = (NOT(0000) AND 0011) OR (0000 AND 1101) 
0011 = ( 1111 AND 0011) OR (0000 AND 1101) 


Possible Problems 


This colorizing will only work on 2-color (i.e. black and white) images, and then only if 
those colors occupy the first and last entries in the color table. Trying to colorize colors 
that are not the first and last color table entries will yield unexpected results. 


This is mainly due to the fact that the colorizing algorithm uses a pixel’s color table index 
value rather than its actual RGB color. To illustrate this, let's assume that foreground and 
background colors are as above, and your image contains yellow with a color table 
index of 1000. The colorizing operation would give: 


ColoredPixelValue 


= (NOT(1000) AND 0011) OR (1000 AND 1101) 
1011 = 


( 
( 0111 AND 0011) OR (1000 AND 1101) 


Since the color table may have any RGB color at the resulting index position, the fina! 
color may not even be close to the source, foreground, or background colors. 


Similar things occur if you are trying to colorize a black and white image when white and 
black do not occupy the first and last positions in the color table. 


The bottom line rules for CopyBit sing in a color environment are these: 
e Thou shalt set thy background color to white and thy foreground color to black 
before calling CopyBits Of CopyMask, unless thou art coloring a monochrome 
image. 


e Thou shalt, when colorizing, make sure that the first color table entry is white 
and the last color table entry is black. 


The second rule is easy to follow because the default color tables are constructed 


properly, and if you are using the Palette Manager (and you are, right?) then it will make 
sure that the color tables obey this rule. 
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How To Colorize—An Example 


This code fragment shows how to implement a color fill, like the paint bucket in MacPaint. 
It relies on three main things: SeedCFili for calculating the fill area, CopyMask for 
actually changing the bits, and QuickDraw colorizing. 


PROCEDURE PaintBucket (where: Point; paintColor: RGBColor); 


VAR 
savedFG : RGBColor; 
offBits : BitMap; 


BEGIN 
{First, create an offscreen bitmap. } 
offBits.bounds := myWindow”’.portRect; 


WITH offBits.bounds DO BEGIN 
offBits.rowBytes := ((right - left + 15) DIV 16) * 2; 


offBits.baseAddr := NewPtr((bottom-top) * offBits.rowBytes) ; 
END; 


{Error Check Here. Make sure NewPtr succeeded! } 


SeedCFill (myWindow*.portBits, of fBits,myWindow%.portRect, 
myWindow*.portRect, where.h,where.v,NIL, 0); 

GetForeColor (savedFG) ; 

RGBForeColor (paintColor); 


CopyMask (of fBits, of fBits,myWindow”~.portBits,myWindow”.portRect, 
myWindow*.portRect, myWindow”.portRect) ; 
RGBForeColor (savedFG) ; 


DisposPtr (offBits .BaseAddr) ; 
END; 


The variable offBits is an offscreen BitMap (not a PixMap) with bounds = 
myWindow^.portRect. SeedCFill effectively creates, in the offscreen BitMap, a 
monochrome image of the bits that we want to paint. Since of fBits contains the exact 


bits that we want to paint, it is used as both the source image and the mask for 
CopyMask. 


By setting the foreground color to the desired paint color, the result is a colorized version 
of the mask (the paint area) being copied onto the window’s PixMap without affecting 
any other bits. 


Technical Note #163 page 3 of 3 Adding Color With CopyBits 


Macintosh Technical Notes C3 


#164: C functions: To declare or not to declare, that is the question. 


see also: MPW C Manual 
Using Assembly Language 
The C Programming Language, Kernighan & Ritchie 
Technical Note 166: MPW C functions using Strings or 
Points as arguments 


Written by: Fred A. Huxham November 2, 1987 


Here’s the low-down on when C functions need not be declared in include 
files. 


“The include files are all screwed up!” 


This is a common misconception people have when they look through the MPW C 
include files. People report that the declaration of a ROM or system call foo() has been 
mistakenly left out of this or that include file. Here’s the low-down on when functions do 
not have to be declared in an include file. 


The Law 


A C function does not need to be declared in an include file if it requires glue code and 
returns a short or long integer as a result. 


Routines that require glue code include: 
° Ail routines that are marked [Not in ROM] in Inside Macintosh 
° All register based routines (Operating System routines) 


° All routines which have strings or points as arguments (and have mixed case 
spellings) 
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#165: Creating Files Inside an AppleShare Drop Folder 


See also: The File Manager 
AppleShare Administrator's Guide 
Software Applications in a Shared Environment 


Written by: Rich Andrews August 3, 1987 
Modified by: Fred A. Huxham November 2, 1987 





i el 


This technical note outlines the steps an application must take to create files 
inside AppleShare Drop Folders. 





The AppleShare File Server allows the creation of Drop Folders. These are folders for 
which the user has the Make Changes privilege (write access), but not See Files (read 
access) or See Folders (search access). For an application to create a file in such a 
folder, the following procedure must be executed in strict order: 


e Issue the Create call to create the new file. 

¢ issue a GetCat Info call (if desired, to preserve the creation date). 

e Set the file's creator and type (and creation date if desired), with a 
SetCatInfo Call. 

e Open each fork of the file with an OpenDeny call with deny readers and 
deny writers access (an attempt to open it with read access will fail). If your 
application will need to write to both forks of the file, it will have to open them 
both now. 

* Write each fork. (Do not attempt to read, any attempt will fail with a privilege 
error.) 

e Close each fork. 


This sequence can be followed for creating any file, not just those in Drop Folders, so 
your application can always create files in this manner. There is no need to special case 
for Drop Folders. 


Note that you will not be able to do a final SetCat Info to Set the modification date to a 
different value. For example, if you were making a copy of an existing file and wanted 
the copy to retain the original creation and modification dates, it will not be possible if the 
destination is in a Drop Folder. 
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#166: MPW C functions using Strings or Points as arguments 


See also: MPW C Manual, Appendix H: “Functions Using Strings or 
Points as Parameters” 


Written by: Fred A. Huxham November 2, 1987 





MPW C 2.0 includes new interfaces to ROM routines which no longer do 
string and point conversions. These new interfaces are described here. 


LL aaa aaaaaaaaaaaaaaaaaasluauatalaualuaaaaasasasasasat$uat$lululassssasl$ltlt$luulul$lMMliÂl 


In MPW C 1.x, the C interfaces to Macintosh OS and Toolbox routines that had strings or 
points as arguments required that: 


1. Strings must be passed as C strings (null terminated). 
2. Points must be passed by address. 


With this method, all these functions would end up calling glue code to: 


1. Convert the C strings to Pascal strings. 
2 Dereference the address of the Point before pushing it onto the stack. 


Because of this your applications ended up being slightly larger (due to the glue code 
needed) and slightly slower (due to the time it takes to execute the glue code). 


MPW C 2.0 includes a new set of ALL CAPS interfaces to Macintosh OS and Toolbox 
routines that have strings or points as arguments. These interfaces require that: 


1. Strings must be passed as Pascal strings (preceded by a length byte). 
2. Points must be passed by value. 


Calling these new routines results in smaller and faster code. In other words, these new 
interfaces are your friend. 
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Some Examples 
First, some Point examples: 


The routine Pt InRect, (old style, mixed case), requires a point passed by address. The 
new interface: 


pascal Boolean PTINRECT (pt, r) 
Point pt; b 
Rect *r; 
extern OxA8AD; 

requires that the Point argument be passed by value. 

And now, some string examples: 


The routine StringWidth, (old style, mixed case), required a C string as an argument. 
The new interface: 


pascal short STRINGWIDTH (s) 
Str255 *s; 
extern OxA88C; 


requires that the argument be passed as a Pascal string. 


Pascal Strings 


Another new feature of MPW C 2.0 is the creation of Pascal strings. You can now create 
a Pascal string by using the “\p” option. The following example demonstrates this new 
feature: 


"This is a C string" 
"\pThis is a Pascal string" 


cStringl 
pString2 


The first line will create a C, null terminated, string, while the second line will create a 
Pascal, preceded by a length byte, string. 
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#167: AppleShare Foreground Applications 
See also: AppleShare Administrator's Guide 


Written by: Fred A. Huxham November 2, 1987 





This technical note outlines the requirements and restrictions of an 
AppleShare foreground application. This information pertains to AppleShare 
versions 1.1 and later. 





An AppleShare server requires a dedicated Macintosh. The server, however, is 
implemented as an interrupt-driven application that runs in the system heap of the server 
machine. This allows the running of a concurrent or foreground application that will live 
in the application heap of the server machine. An example of a foreground application is 
LaserShare, the LaserWriter spooler available from Apple. 


An AppleShare foreground application has a few additional restrictions and 
requirements beyond that of a normal Macintosh application. 


1. In order for the AppleShare server to recognize your program as a foreground 
application, it must contain a resource of type 'fgnd', ID=1, containing a longword of 
$00000000. 


2. A foreground application is not allowed to make any file system calls outside of any 
server volume’s Server Folder. If a foreground application needs to create files, it is 
recommended that the application create a folder inside the Server Folder and then 
create all its files within that folder. For example, all print spooler or e-mail files must 
reside within the Server Folder, and preferably, within a folder that is inside the Server 
Folder. To find the Server Folder: 


e Make a PBHGet Vinfo call on the volume. 
. Examine iovFndrInfo[8] (long integer) 
. if iovFndrInfo[8] is a non-zero value, then the value is the directory ID of 


the Server Folder. 


3. A foreground application is not allowed to make any file system calls or to modify in 
any way: the AppleShare server application, Parallel Directory Structure, or the User or 
Group Data Bases within the Server Folder of any volume. Also, do not rely on the 
presence or formats of any of these structures, as they are subject to change! 
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4. A foreground application must not eject or unmount any volumes that are not in drives 
1 and 2. . 


5. A foreground application must not call the Shutdown trap; rather, it should quit by 
calling ExitToShell1 or by dropping out of its main event loop. 
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#168: HyperCard 'snd ' Resource 
See also: The Sound Manager 


Written by: Chris Knepper November 2, 1987 


HyperCard’s play command: (1) expects the name of a format 2 'sna ' 
resource, and (2) accepts stop as a parameter (an undocumented feature). 


HyperCard has the ability to play sounds stored in 'snd ' resources. The HyperTalk 
command to play these sounds is: 


play <"voice"> [tempo <tempo>] <"notes"> [# | b] [octave] [duration] 


(1) The "voice" parameter is the name of an 'snd ' resource. The 'snd ' resource 
which HyperTalk’s play command expects is the format 2 'snd ' resource. All format 2 
"snd ' resources can be played by HyperCard. These use the “Sampled Sound 
Synthesizer.” 


Both format 1 and format 2 'snd ' resources are documented in inside Macintosh 
volume V in the version dated 17 Aug 87, available from APDA. The description of format 
2 'snd ' resources is missing from earlier versions. 


To see if a sound resource is format 1 or 2, use ResEdit or the MPW Tool DeRez to look at 
the first word of the resource. This will be either $0001 or $0002 depending on whether 
the resource is a format 1 or 2 resource. Note that all 'snd ' resources in the System 
file are format 1. Also, note that the 'snd ' resources which come with HyperCard, 
“Silence”, “Harpsichord”, and “Boing” are all mistakenly labeled as format 1 resources 
even though they are, in fact, format 2. — 


The HyperCard Technical Reference Package available from APDA (#KMBHTL) has a 
file “Flute” containing digitized sound of a flute, produced by the MacNifty Sound Wave 
software and Sound Digitizer hardware. To convert this SoundCap file to a format 2 
‘snd ' resource, use the HyperCard stack SoundCapMover which comes with the 
Package. This stack calls an XCMD whose source is also included on the disk: 
SoundCapToRes.c. 


(2) There is an undocumented feature of HyperTalk’s play command: 


play stop 
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This command stops any sound currently being played. 
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#169: HyperCard 1.0.1 Anomalies 
see also: HyperCard Script Language Guide (APDA) 
Written by: Chris Knepper November 2, 1987 





This technical note describes some HyperCard anomalies with which 
developers should be familiar when developing stackware. 


—_—_ COO ee 


visual effect on a Macintosh II 


On a Macintosh Il’s screen, it is necessary to set the screen to 2 grays (1 bit depth) in the 
Control Panel’s Monitor in order to see the visual effects chosen with HyperTalk’s visual 
effect command. For example, the following handler in a button script requires 1 bit 
depth in order to display the checkerboard effect: 


on mouseUp 
visual effect checkerboard 
go to next card 

end mouseUp 


High Disk Space Requirement for Background Printing 


Running HyperCard under MultiFinder 1.0 with Background Printing enabled requires 
extensive available disk space for printing large jobs, such as printing a stack (with Print 
Stack... in the File menu) of 100 cards. This is due to Print Monitor’s spooling the job to 
disk. 


Word wrap with quoted phrases 


You will notice in HyperCard 1.0.1, that the word wrap algorithm handles quoted phrases 
differently than standard TextEdit handles these phrases. So, when a quoted phrase 
begins near the end of a line in a field, the quoted words, such as “La Traviata”, would 
wrap between the initial quote and the first letter quoted. Thus, beginning a quoted 
phrase near the end of a line in the To Do stack’s field would render the following: 
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To Do 


Run errands 


O04 6 O6S6 Ce ae ESET PSSERSE SEE FOG 65S Ons oy EEE UEOSFE EOD AceenS Lh eth tet beteted bbe t tattle ILI ITT TTT eT TTT 


29 O46 FS604 Cede ee FEST UOTE EES EES OSS ChE ESE EES EE STOR PES SN6 SHS FESS CSTE DEE ESD ASS a FSSC L REGS HES COR EGOS 





This may be fixed by resizing the field slightly narrower with the field tool, or by putting a 
carriage return before the quoted word: 





To Do = 





Run errands 


SE FS FEO S44 SHAS TESTES TAS EH SEE DAS ADA OS HHO EHS PEO SEE COR ROSH OOH thyr BE SOR O86 OOS S46S65 SUTTER FUEORAESE RA 


BOATERS AERATOR CUTE ESE OETA E DARED EAS Shh Sh OEE COE EES ONE OOS Adm OOS SSE PES ONT CORRES Danat ROSEN EE TEROFETEDSseonaney 


Beware the on idle Handler 


You will notice that the on idle handler in a script executes while you're typing into a 
field. This means that the on idle handler takes away the insertion point in certain cases 
while you're typing into a field, resulting in the computer beeping since it can't interpret 
the characters typed, or in the characters being displayed in the Message Box if it is 
open. A particularly insidious example is the following handler in a background script: 


on idle 
put the time into bkgnd field "Time" 
end idle 


lf you are typing into a field, this handler will remove the insertion point from the field 
whenever the time changes, for example from "6:42 PM" to "6:43 PM", requiring 
HyperCard to change the contents of bkgnd field "Time". 


Launching Applications under MultiFinder 1.0 with open 


HyperCard enables users to launch applications and, optionally, to specify that the 
application open a document. The syntax follows: 


open <application> 
open <document> with <application> 


Essentially, HyperCard 7.0.1’s algorithm is: it quits, <application> launches and, 
optionally, opens <document>. If MultiFinder isn’t running when the user quits from 
<application>, then HyperCard launches and returns automatically to the card from 
which the open command was issued. If MultiFinder is running, the application quits to 
the Finder. Then, the next time HyperCard is launched manually, it will go to the card 
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from which the open command was issued. 


The values of global variables are not saved automatically when HyperCard quits after 
the open, so the stack’s scripts must save them explicitly—perhaps by saving the current 
state of globals to an invisible field in the stack or to a disk file via a HyperTalk export text 
script (using HyperTalk’s open file fileName, write, andclose file fileName 
commands) or an XCMD. The HyperTalk messages suspend and resume are sent, 
respectively, when HyperCard quits because of HyperTalk’s open command and when 
HyperCard next launches after an open command. 


You should be aware of a bug with open when running under System 4.1 or 4.2 and 
MultiFinder 1.0: HyperCard 1.0.1 has some difficulty locating <document> if it’s specified 
in the open command. 


For example, with MacWrite in the folder Applications on the disk HD 20, and with the 
document Sample in the folder Documents on the disk HD 20, the following commands 
from the Message Box, or from a HyperTalk script fails to open Sample with MacWrite. 
[Note that the directories in the Home stack (on the Documents card ":Documents:" or 
"HD 20:Documents:" and on the Applications card ":Applications:™ Or "HD 
20:Applications:") have been set correctly.]: 


open "HD 20:Documents:Sample"™ with "HD 20:Applications:MacWrite" 
open ":Documents:Sample" with "“:Applications:MacWrite" 
open "Sample" with "MacWrite" 


Although MacWrite launches correctly, a Stop Alert appears with an error message “This 
document can’t be opened.” After dismissing the Alert by pressing OK, the document 
may be opened with the Open... command in MacWrite’s File menu. 


If this functionality is desired, one workaround is to turn MultiFinder off, then open will 
correctly open Sample. Another workaround is to put the document Sample at the root of 
the volume. In this case, Sample is located at “HD 20:Sample” and MacWrite may be 
placed in the Applications folder. Then, the command: 


open "Sample" with "“MacWrite" 
works correctly. 


Note: In versions of HyperCard later than 1.0.1, open works differently: it doesn’t quit 
under MultiFinder. If there is insufficient memory to launch <application> then 
HyperCard does nothing. Also, the bug with locating Sample, as described above, is 
fixed. 


Optimizing find 

HyperTalk’s find command works best when at least 3 characters are specified and the 
stack has recently been compacted with the Compact Stack item in the File menu. 
Please note that specifying less than 3 characters, or using word break characters, such 


as the space or dash, for any of these 3 characters will result in a slower find. 
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The more trigrams that are specified for the find (strings with at least 3 characters), the 
faster the find. Thus, the following find in a company phone list: 


find “Fred Dev Tech" 
would find “Fred Huxham” in “Developer Technical Support” faster than would: 


find "Fred" 


Selecting contents of a field with HyperTalk 


There are several ways of selecting text in a field with HyperTalk: by simulating a double 
click, a Shift-Click, or a drag. The first two work, the last doesn’t. Three button scripts are 
printed here, the first shows a method of simulating a double click in a HyperTalk script. 
This script performs a double click at the loc of the field (approximately the center of the 
field’s rectangle): 


on mouseUp -- card button "Double Click" 
click at the loc of field "myFieldl" 
click at the loc of field "myFieldl” 
if the selection is empty 
then put "No selection” into card field "DoubleClickSelection" 
else put the selection into card field "DoubleClickSelection" 
end mouseUp 





This second script demonstrates a method of selecting text with the Shift click using 
HyperTalk: 


on mouseUp -- card button "Shift Click” 

get the rect of bkgnd field "myField2” 

click at item 3 to 4 of it 

click at item 1 to 2 of it with ShiftKey 

if the selection is empty 

then put "No selection" into card field "ShiftClickSelection" 

else put the selection into card field "ShiftClickSelection" 
end mouseUp 


: laity ale) zi) ae) The quick brown fox 
saareannantt etl i over the e lazy dog. jumps over the lazy dog. 


The third script presents a method of selecting text by dragging over it. This method, 
however, requires with shiftKey as a parameter to drag in order to work correctly: 





on mouseUp -- card button "Drag Shift" 
get the rect of bkgnd field "myField3" 
drag from item 1 to 2 of it to item 3 to 4 of it with shiftKey 
if the selection is empty 
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then put "No selection” into card field “DragShiftSelection" 
else put the selection into card field "DragShiftSelection" 
end mouseUp 





HyperCard Title Bar Highlighting 


Running HyperCard 1.0.1 under MultiFinder 1.0, you will notice that when switching 
HyperCard to the background, HyperCard’s title bar highlighting is incorrect when either 
the Message box, and/or the Tools tear-off menu, and/or the Patterns tear-off menu are 
displayed. In these cases, HyperCard’s title bar is highlighted, as if it were the 
foreground application. 


dial 


The dial command ignores "#" and “*" when dialing with the Macintosh speaker. Thus, 
the following command doesn’t work: 


dial "#" 


This is a bug in HyperCard 1.0.1 which is fixed in subsequent versions. Note that it is still 
possible to dial "#" and "*" with the with modem option for dial as follows: 


dial "*" with modem "ATDT" 


Since the Phone stack shipped with HyperCard 1.0.1 strips out "#" and "*" before passing 
any arguments to its dial handler, this last example won't work in the Phone stack. 


closeField Message 


if the user has manually changed text in a field, then the closeField message is sent to 
the field when the Enter key is pressed, when the Tab key is pressed to move to the next 
field, when the user clicks outside of the field, or in certain cases, when the user then 
clicks on a button. One of the cases in which the message is sent is when the button 
script moves the user to the next or previous cards (go to prev cardOfgo to next 
card). Otherwise, the closeField message is not sent to the field. 


If your stack depends on the closeField message being sent every time a field is 
changed, regardless of which button the user subsequently clicks, then you should 
modify your scripts to ensure this. This may be done as follows. 


in the card script, modify the openCard handler to include the following: 
on openCard 
global myField 
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put bkgnd field 1 into myField 
end openCard 


In the field script, modify the closeField handler to include the following: 


on closeField 
global myField 


put bkgnd field 1 into myField 
end closeField 


In the button script, modify the mouseDown (or mouseUp) handler to incorporate the 
following: 


on mouseDown -- bkgnd button 2 
global myField 


if myField is not bkgnd field 1 then send closeField to bkgnd field 1 
end mouseDown 


Then, when the user edits bkgnd field 1 and then clicks on bkgnd button 2, HyperCard 
will send the closeField message to bkgnd field 1 If and only if the user has changed 
its contents and the closeField message has not already been sent. 


exit to HyperCard 


The exit to HyperCard command, which exits from anywhere in a script back to 
HyperCard, doesn’t close open files! So be sure you close them before invoking this 
command. This is a bug in HyperCard 1.0.1 which is fixed in subsequent versions. 


Maximum Limit on Number of Background Fields 


A stack with a background containing more than 126 background fields or with a card 
containing more than 126 card fields will result in serious stack corruption during the 
Compact Stack procedure. This is a bug in HyperCard 1.0.1 which is fixed in future 
versions. To find out how many background fields are in the current background, type the 
following HyperTalk command into the Message Box and press Return: 


the number of fields 


To find out how many card fields are in the current card, type the following HyperTalk 
command into the Message Box and press Return: 


the number of card fields 
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mouseDown and mouseUp Messages in Scrolling Fields 


The mouseDown and mouseUp messages aren't sent to scrolling fields when the mouse 
is clicked in the field’s scrollbar. 


Passing “it” as a Parameter to Handlers 


Passing it as a parameter to a handler is no different than passing any other parameter 
to a handier. This means that: it is always a local variable to the handler in which it is 
used, and it is passed to a handler by value, not by reference. 


Private Access 


HyperCard 1.0.1’s Private Access feature, which enables stacks to require users to type 
in the Password when opening the stack, has a fatal bug. There is an instance in which 
changing a stack to Private Access will prevent HyperCard from ever again opening that 
stack. 


This bug occurs as follows: create a new stack, assign a password via the Protect Stack... 
item, Quit HyperCard. Launch HyperCard, go to the stack just created, set Private Access 
via the Protect Stack... item, Quit HyperCard. The stack is now inaccessible to 
HyperCard. This is a bug in HyperCard 1.0.1 which is fixed in the next version. In the 
interim, it is probably best not to set the Private Access feature after setting the password. 
Instead, set the Private Access feature when no password has yet been assigned. Then, 
HyperCard will prompt for the password. Choose a password and HyperCard may now 
access the stack and the Private Access feature works correctly. 


find in Card fields 


There is a bug with HyperTalk’s find command when used to find a string in card fields. 
in a stack with the card field “Name” whose contents are “Jim Friedlander,” the following 
find doesn’t work: 


find “Jim” in card field 1 
find "Jim" in card field "Name" 


This is a bug in HyperCard 1.0.1 which may be fixed in future versions. 
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#170: HyperCard File Format 
see also: HyperCard User’s Guide 
Written by: Chris Knepper November 2, 1987 





The file format of a HyperCard stack is proprietary and will not be 
documented. In most cases, you will not need to know the file format of a 
HyperCard stack, but instead can access data for input and output by using 
HyperTalk. 





Currently there are no plans to document the file format of the stacks which HyperCard 
produces. However, a more flexible alternative, such as a toolbox of routines to interface 
code and HyperCard files, will be available in the near future. At that time, all Certified 
Developers will be notified. 


Since HyperCard allows developers to control data input and output to files using 
HyperTalk, most needs for file formats may be easily met by using HyperTalk and writing 
scripts. In particular, the following HyperTalk commands are useful: 


open file fileName 
close file fileName 
read from file fileName until <delimiter> 


Versions of HyperCard after 1.0.1 come with three example scripts for demonstrating file 


I/O: an Import script, an Export Data script, and an Export Text script. These will provide 
frameworks for building your own custom file 1/O routines. 
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#171: PackBits Data Format 


See also: The Toolbox Utilities 
Technical Note #86—MacPaint Document Format 


Written by: Cameron Birse November 2, 1987 





This technical note describes the format of data packed by the toolbox utility 
PackBits. Normally, you would not need to know the format of the packed 
data, since you can simply unpack it using the unPackBits call. This 
information is provided for the terminally curious, and those manipulating 
MacPaint documents by hand. WARNING! This information is provided 
for informational purposes only! It is accurate for now, but may 
change in the future. 





First there is a byte which specifies whether or not the the data is packed, and is also the 
count byte. It is a negative number if packed (i.e. the high bit is set). If the high bit is set, 
then that complete byte is a two’s complement number that tells you how many bytes 
were packed. If it is a positive number, then it is simply a zero based count of how many 
discrete data bytes there are. Consider the following example: 


UnPacked data: 


AA AA AA 80 00 2A AA AA AA AA 80 00 2A 22 AA AA AA AA AA AA AA AA AA 
AA 


After being packed by PackBits: 


FE AA ; (-(-2)+1) = 3 bytes of the pattern SAA 
02 80 00 2A ; (2)+1 = 3 bytes of discreet data 
FD AA ; (-(-3)+1) = 4 bytes of the pattern SAA 
03 80 00 2A 22 ; (3)+1 = 4 bytes of discreet data 
F7 AA ; (-(-9)+1) = 10 bytes of the pattern SAA 


-OR- 


FE AA 02 80 00 2A FD AA 03 80 00 2A 22 F7 AA 
x 


* * * * 


The bytes with the ““” under them are the count/flag bytes. PackBits will only pack the 
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data when there are 3 or more consecutive bytes with the same data, otherwise it just 
copies the data byte for byte (and adds the count byte). 
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#172: Parameters for MDEF Message #3 
See also: The Menu Manager 


Written by: Chris Derossi November 2, 1987 


In order to support popup menus, menu definition procedures (MDEFs) must now 
respond to a new message, mPopupMsg. mPopupMsg IS Message number 3. When your 
MDEF is called with this message, it should calculate the rectangle in which the popup 
menu should appear. 


The interface to an MDEF is 


PROCEDURE MyMDEF (message: Integer; theMenu: MenuHandle; VAR menuRect: 
Rect; hitPt: Point; VAR whichItem: Integer); 


For mPopupMsg, the message parameter will be 3 and theMenu will be a MenuHand1e to 
your menu. The MDEF should compute a rectangle for the menu such that the item 
passed in whichItem will be displayed at hitPt. See the figure below: 


Font: |Chicago <-—Kem #2 Font:/Chicago 


Helvetica 
Monaco 





The hitPt parameter, though, is NOT a Point. Instead, this parameter is used to pass 
the top left of the item, passing the top coordinate and then the left coordinate. This is 
the opposite order of the fields in a Point. The values can be used together as a 
LongInt, with left in the high word and top in the low word, or separately as two 
Integers. 


A more correct Pascal interface to the MDEF (for the mPopupMsg only) would be: 


PROCEDURE MyMDEF (message: Integer; theMenu: MenuHandle; VAR menukRect: 
Rect; top, left: Integer; VAR whichItem: Integer); 
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Note: The MPW interface files incorrectly list mPopupMsg as 4; it should be 3. 
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#173: PrGeneral Bug 


See also: The Print Manager 
Technical Note #128—PrGeneral 


Written by: Scott “ZZ” Zimmerman November 2, 1987 


This technical note documents a bug in the implementation of the PrGeneral 
procedure in the LaserWriter driver version 4.0. The bug has to do with the 
format of the information returned by the GetRsIData opcode. This technical 
note will also describe a workaround for the problem. 


One of the opcodes supported by the PrGeneral procedure (Technical Note #128) is 
named GetRslData. The GetRslData operation initializes a resolution record that is of 
the following form: 


TRslRg = RECORD {used in TGetRsl1Blk} 
iMin: Integer; {0 if printer only supports discrete resolutions} 
iMax: Integer; {0 if printer only supports discrete resolutions} 
END; 


TRslRec = RECORD {used in TGetRs1Blk} 
iXRsl: Integer; {a discrete, physical X resolution} 
LYRsl: Integer; {a discrete, physical Y resolution) 
END ; 


TGetRSs1Blk = RECORD {data block for GetRslData call} 


iOpCode: Integer; {input; = getRslDataOp} 

ifrror: Integer; {output } 

1Reserved: LongInt; {reserved for future use} 

iRgType: Integer; {output; this declaration is for RgTypel} 
XRs1lRg: TRslRg; {output; range of X resolutions} 

YRsl1Rg: TRS1Rg; {output; range of Y resolutions} 
iRslRecCnt: Integer; {output; how many RslRecs follow} 
rgRslRec: ARRAY [1..27] 


OF TRslRec; {output; number used depends on printer type} 
END ; 


The LaserWriter 4.0 implementation has a bug that affects the yRs1Rg and XRs1Rg fields 
of the TGetRs1B1k record. The correct values for the fields are: 


TGetRs1Blk.XRslRg.iMin := 25; 
TGetRs1Blk.XRslRg.iMax := 1500; 
TGetRs1Blk.YRslRg.iMin := 25; 
TGetRs1Blk.YRslRg.iMax := 1500; 


Unfortunately, the information returned by the LaserWriter 4.0 version of PrGeneral Is: 
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TGetRs1Blk.XRslRg.iMin := 25; 
TGetRs1Blk.XRslRg.iMax := 25; 
TGetRsIBlk.YRslRg.iMin := 1500; 
TGetRslBlk.YRslRg.iMax := 1500; 


The recommended workaround for this problem is to use the PrDrvrVers function 
(inside Macintosh 11-163) to find out which version of the print driver you are using. If you 
are using 4.0, modify the resolution data before using it. The following code fragment 
illustrates this workaround: 


PROCEDURE CheckRslRecord(VAR theRslRecord: TGetRs1Blk); 
CONST 
BogusDriver = 40; 
BEGIN 
IF PrDrvrVers = BogusDriver THEN BEGIN 
theRslRecord.XRs1lRg.iMax := theRslRecord.YRslRg.iMax; 
theRslRecord.YRsliRg.iMin := theRslRecord.XRslRg.iMin; 
END; 
END; 


When the bug is fixed in a future version of the driver, the CheckRslRecord procedure 
will no longer have any effect on the resolution record. This will make sure your 
application gets the correct resolution data no matter which version of the driver is being 
used. 
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#174: Accessing the Script Manager Print Action Routine 
See also: The Script Manager 


Written by: Mark Davis November 2, 1987 





This technical note describes how Print Drivers can access the Script 
Manager Print Action routine to print unconventional text, such as Japanese 
or Arabic. 





General Notes 


Scripts such as Japanese or Arabic modify the normal QuickDraw text handling in order 
to represent text properly. On the screen, this is done by trapping StdText and 
Sst dTxtMeasure, and transforming the text before printing. For example, for Hebrew or 
Arabic the text might be reversed, since text normally goes from right to left in those 
scripts. 


Print drivers require slightly different handling, for two reasons: 


1. A print driver might not call the standard QuickDraw procedures. For example, the 
LaserWriter writes directly in PostScript instead. 


2. A print driver might need to format the text, for accurate line-layout. In this case, the 
text needs to be transformed before the driver performs line-layout. If the driver is 
spooling the text, and will replay the text a second time, the text cannot be transformed a 
second time, since that would ruin the appearance. 


For example, the ImageWriter driver calls QuickDraw procedures twice, once to spoo! 
and once to unwind the spooling. The text must be transformed when spooling, so that 
line layout can be done, but when unwinding, the transformation must be turned off 
completely. 


Note that some drivers, such as the LaserWriter, use QuickDraw re-entrantly: the 
application program calls a QuickDraw routine, which is directed to the driver's 
grafProcs, which in turn call QuickDraw internally to put up status messages on the 
screen. The Print Action procedure handles the text properly so that the text 
transformations are enabled during the re-entrant calls, so that the status messages will 
be properly formatted. 
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When To Call the Print Action Routine 


The Script Manager Print Action routine allows the print driver to be independent of the 
particular scripts being used. The printing driver should call this routine whenever it 
changes the grafProcs in the printing grafPort. The Print Action routine will then 
substitute grafProcs of its ownin the grafProcs record, saving the original routine 
addresses. 


The Print Action routine will actually call a Print Action routine for each script system that 
is currently installed. Each of the script Print Action routines will do the appropriate tasks 
for its system. 


Calling the Print Action Routine 


To call the Print Action routine, the driver should use the following code: 


int1Globals equ $ba0 ; international globals 
printActionoff equ $16 ; offset to PrintAction proc ptr 


; get procedure pointer to call 


tst.w Rom85 ; on a Macintosh + or better? 
blit.s @PrintActionDone ; no, skip 

move .1 intl1Globals,d2 ; get international globais 
ble.s @PrintActionDone ; not there, skip 

move. l d2,a0 ; in address register 

move. l printActionOff (a0) ,da2 ; get print action address 
beq.s @PrintActionDone ; not there, skip 

move .1l d2,a0 ; in address register 


; set up arguments to call 


move .1 <myPort>,d0 ; pass the port 

move .W <myVerb>, dl ; pass the verb 

jsx (a0) ; call the procedure 
@PrintActionDone 


Print Action Routine Verbs 


There are currently three verbs to pass to the Print Action routine. 


paUnwindText equ -1 
paSpoolText equ 1 
paNoQuickDraw equ 3 


Use the paUnwind verb to ensure that the text is not transformed before your StdText 
procedure receives the text. This verb is used when playing back stored text that has 
already been transformed. 
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The other two verbs (paNoQuickDraw and paSpoolText) are used to ensure that the 
text is transformed before your StdText procedure receives the text. The paSpoolText 
verb is used when your driver will use QuickDraw to image the text in the printing 
grafPort. The paNoQuickDraw verb is used when the text is not drawn into the printing 
port by going through QuickDraw (e.g. the LaserWriter). In that case some languages 
(e.g. Japanese) which use an extended font structure may need to recast the text calls as 
CopyBits Calls. 


As mentioned above, some applications may call QuickDraw from within the driver, as 
when a status window is updated. During any StdTxtMeasure Calls in the driver during 
the application’s call to StdText, the port is checked against the printer port. If they 
match, then the text is not transformed. Otherwise, the text is transformed. 


The solutions adopted by the Print Action routine assume that the print driver does not 
measure or draw text except within calls to StdTxtMeasure or StdText. If your driver 
does text buffering (as for line layout), make sure that any measurements are performed 
within these two calls. For example, you might buffer both the text and its screen width as 
measured by QuickDraw. 
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#175: SetLineWidth Revealed 


See also: LaserWriter Reference Manual 
PostScript Language Reference Manual 
PostScript Language Tutorial and Cookbook 


Written by: Scott “ZZ” Zimmerman November 2, 1987 


This technical note describes the internal implementation, and correct 
method of using, the Set LineWidth Picture Comment. 


The SetLineWidth picture comment provides a way of accessing PostScript's 
‘setlinewidth’ operator. Since the LaserWriter resolution is roughly four times that of the 
Macintosh screen, fractional line widths can be printed. The SetLineWidth 
PicComment provides a way for applications to access these fractional line widths 
through PostScript, without having to use floating point numbers. 


First of all, the LaserWriter has an internal state that is stored in a number of PostScript 
variables. For more information on PostScript variables, see the PostScript Language 
Reference Manual. Some operations performed on the LaserWriter cause the values of 
these variables to change. One of these variables contains the width of the printers pen. 
The SetLineWidth picture comment works by changing the value of this variable. 


Before we look at what the SetLineWidth comment does, let’s look at the argument 
passed to the comment. The argument is represented as a QuickDraw Point, however it 
is interpreted by the LaserWriter as a fraction. The LaserWriter interprets a point (h, v) 
to be a real number whose value is (v / hn). This means that a point whose value is 
h=2, v=1, will be converted to 0.5 before being used by the LaserWriter. If you wanted to 
pass a value of 0.25, you would pass a point whose value is h=4, v=1. For 1.25, pass a 
point, h=4, v= 5. 


In addition to the pen width variable, there is a variable that is used for scaling the pen’s 
width. This variable, named pnm for PeN Multiplier, contains a real number which is 
applied to the pen width. The default value of pnm is 1.0, which causes no scaling of the 
line width. 


Whenever the Set LineWidth PicComment is sent to the LaserWriter, the current value 
of pnm is replaced by the value passed to the PicComment. The current pen size is then 
scaled by the new value of pnm. The following example will display four lines of different 
sizes. It is meant to illustrate the interaction between the QuickDraw PenSize procedure 
and the SetLinewWidth PicComment. 


TYPE 
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widthHdl = “widthPtr; 
widthPtr = “widthPt; 
widthPt = Point; 


VAR 
theWidth: widthHdl; 


BEGIN 


(* Initialize the print manager as per Inside Macintosh II-1i55. *) 


At this point, it is assumed that PrPageOpen has been called, and the print manager is 


ready to accept data. 


The first thing we do is set the scaling factor to 1.0. This way, no scaling will be 


performed when we call PenSize. 


theWidth := widthHdl (NewHandle (SizeOf (widthPt))); 

(*Real programs do error checking here... *) 

SetPt (theWidth**, 1, 1); 

PicComment (SetLineWidth, SIZEOF(widthPt), Handle (theWidth) ); 


Here we call PenSize. Because the pnm has been set to 1.0, the pen size(1,1) times the 


multiplier (1.0) yields 1,1. 


PenSize(l, 1); 

MoveTo(50, 100); 

LineTo(500, 100); 

MoveTo(50, 125); 

DrawString('l point thickness.'); 


Now we will use the SetLinewidth PicComment to change the pen size. 


when we change the scaling factor, the pen size changes as well. 


SetPt (theWidth**, 1, 5); 

PicComment (SetLineWidth, SIZEOF(widthPt), Handle (theWidth)); 
MoveTo(50, 200); 

LineTo (500, 200); 

MoveTo (50, 225); 

DrawString('5.0 times 1 point pen size = 5 point thickness.'); 


Note that 


lf any calls to PenSize are made at this point, the new pen size will be scaled by 5.0. 
This is because the Set LineWidth PicComment is still in effect. We will now send a 


SetLineWidth PicComment to revert the scaling factor back to 1.0. 


SetPt (theWidth**, 5, 1}; 

PicComment (SetLineWidth, SIZEOF(widthPt), Handle (theWidth) ); 
MoveTo (50, 300); 

LineTo (500,300); 

MoveTo(50, 325); 

DrawString('0.2 times 5 point pen size = 1 point thickness.'); 


Since the scaling is once again 1.0, PenSize calls at this point will not be scaled. Here 
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we explicitly set the scaling factor to 1.0 before changing the pen size. This makes it 
easier to see what scaling will be applied to the next call to PenSize. 


SetPt (theWidth**, 1, 1); 

PicComment (SetLineWidth, SIZEOF(widthPt), Handle (theWidth) ); 
PenSize(l, 1); 

MoveTo(50, 400); 

LineTo (500, 400) ; 

MoveTo(50, 425); 

DrawString('1.0 times 1 point pen size = 1 point thickness"); 
(* Dispose of the handle when you are through with it! *) 
DisposHandle (Handle (theWidth) ) ; 


When printed, the above example will produce the following: 


1 point thickness. 


5.0 times 1 point pen size = 5 point thickness. 


0.2 times 5 point pen size = 1 point thickness. 


1.0 times 1 point pen size = 1 point thickness. 


To summarize, there are four things to remember when using the SetLineWidth 
PicComment: 


1. 


The argument to the Set LineWidth PicComment is specified as a point, though it is 
actually interpreted by the LaserWriter as a real number. The point value is 
specified as h, v, and the LaserWriter interprets the value as v / h. 


The SetLineWidth PicComment affects both the height and width of the pen, even 
though the name suggests otherwise. 


When you send the SetLinewidth PicComment, the current pen size will be 
scaled. Any drawing that is done after the PicComment is set, will be done with the 
scaled pen size. 


When you call the QuickDraw PenSize procedure, the pen size will be scaled after 
it has been set. For example, if your scaling factor is 0.5, and you set the pen size to 
2,2, the actual pen size will be 1,1. If you don’t want the scaling to occur, make sure 
to send a SetLinewWidth PicComment, with the point argument set to 1,1. The next 
call to PenSize will then be scaled by 1.0, which will have no effect. 


Technical Note #175 page 3 of3 SetLineWidth Revealed 


Macintosh Technical Notes $ 


#176: Macintosh Memory Configurations 
Written by: Cameron Birse November 2, 1987 


This technical note describes the different possible memory configurations 
using Single Inline Memory Modules (SIMMs) for the Macintosh Plus, 
Macintosh SE, and Macintosh II. Special thanks to Brian Howard for the 
Macintosh Plus, and SE Drawings, and the inspiration for the 
not-as-spectacular Macintosh II drawings. 


Here in Macintosh Technical Support we have received numerous questions about the 
many different possible configurations of the SIMMs on the different Macintoshes, so Il 
attempt to answer these questions in this technical note, as well as provide a showcase 
for some outstanding MacDraw work by Apple engineer Brian Howard. 


Macintosh Plus: 
The Macintosh Plus has the following possible configurations (see fig. 1): 


512K, using two 256 Kbit SIMMs 

1 MB, using four 256 Kbit SIMMs 

2 MB, using two 1Mbit SIMMs 

2.5 MB, using two 1Mbit SIMMs, and two 256Kbit SIMMs 
4MB, using four 1Mbit SIMMs 


it is important to place the SIMMs in the correct location when using a combination of 
SIMM sizes, as in the 2.5 MB example, and to make sure the right resistor are cut. Refer 
to Figure 1 for the correct location of the SIMMs, and size resistors. 

Macintosh SE: 

Same as the Macintosh Plus, except the physical locations are different (see fig. 2). 
Macintosh Il: 

You must always upgrade in four SIMM chunks, as the Macintosh II is a 32 bit data bus, 
and the SIMMs are eight bits each. The eight SIMM connectors are divided into two 
banks of four called bank A and bank B. Bank A is the bank closest to the edge of the 


board (see fig. 3). Unlike the Macintosh Plus and Macintosh SE, there are no resistors to 
cut, you need only install the SIMMs in the correct place, and you’ll be up and running. 
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The configurations you can have are: 


1MB four 256k SIMMs in bank A 

2MB eight 256k SIMMs in banks A&B 

4MB four 1Mb SIMMs in bank A 

SMB four 1Mb SIMMs in bank A, and four 256k SIMMs in bank B 
8MB eight 1Mb SIMMs in banks A&B 


Again, it is important to make sure the right size SIMMs are in the right Bank, when you 
are using a combination of SIMMs, the larger SIMMs must be in Bank A. When you are 
using only four SIMMs, they must be in Bank A as well. 
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#177: Problem with WaitNextEvent in MultiFinder 1.0 


See also: Technical Note #158—Frequently Asked MultiFinder 
Questions 
Technical Note #180—MultiFinder Miscellanea 


Written by: Jim Friedlander November 2, 1987 


This Technical Note discusses a bug in WaitNextEvent in MultiFinder 1.0. 
This bug only occurs when WaitNextEvent is called from the background. 
This bug will be fixed in the next release of MultiFinder. 


In MultiFinder 1.0, applications that use WaitNextEvent: 


FUNCTION WaitNextEvent (mask: INTEGER; VAR event: EventRecord; 
sleep: LONGINT; mouseRgn: RgnHandle): BOOLEAN; 


pascal Boolean WaitNextEvent (mask,event, sleep,mouseRgn) 
unsigned short mask; 
EventRecord *event; 
unsigned long sleep; 
RgnHandle mouseRgn; 


should not call WaitNextEvent from the background with a value of sleep that is 
greater than 50. This value has been determined empirically for a Macintosh I; larger 
values can be used on the Macintosh Plus and the Macintosh SE. If an application uses 
a value of sleep greater than 50 when running in the background, MultiFinder 1.0 will 
hang under the following circumstances: 


¢ The application that ts calling WaitNextEvent with sleep > 50 has been put 
in the background. 

e That application becomes the foreground application when another 
application (including SysDAHandler) quits. 


If you use a value of sleep that is less than 50, this problem will not occur. If you use an 
algorithm to calculate sleep, make sure that the maximum is clipped to 50. 


This problem will be fixed in the next release of MultiFinder. You can call SysEnvirons 


to test for the system version number. This bug will not happen when the System version 
is greater than $0420. 
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#178: Modifying the Standard String Comparison 


See also: The International Utilities 
Written by: Mark Davis & 
Priscilla Oppenheimer November 2, 1987 





This technical note describes how to modify the standard string comparison 
by constructing an it12 resource. Developers may want to modify the 
standard string comparison if Apple's comparison doesn’t meet their needs or 
if Apple has not written a string comparison routine for the language that 
concerns them. 


a a 


General Structure 


The it12 resource contains a number of procedures that are used for accurate 
comparison of text by the Internationa! Utilities Package. Refer to Inside Macintosh, 
volume V for an explanation of the algorithm used. The default it12 for standard English 
text, which does no special processing, has the following form: 


: normal Include/Load statements 
Include 'hd:mpw:aincludes:ScriptEqu.a' 


Print On, NoMDir 
String AsIs 
; dispatch table at the front of the code 
Inti1 Proc 
With IUSortFrame, IUStrData 
HookDispatch 
dc.w ReturnEQ-HookDispatch ; InitProc = 0 
dc. ReturnEQ-HookDispatch ; FetchHook = 2 


Ww Ld 

W ReturnEQ-HookDispatch ; VernierHook = 4 
dc.w ReturnEQ-HookDispatch ; ProjectHook = 6 

W ReturnEQ-HookDispatch ; ReservedHookl = 

wW ReturnEQ-HookDispatch ; ReservedHook2 = 


rts 
ReturnEQ 
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cmp .w d0, do ; set cc EQ 


EndWith 
EndWith 
End 


If modifications need to be made to the comparison process, then one or more of the 
dispatches will be modified to point to different routines: 


de.w InitProc-HookDispatch ; InitProc = 0 
dc.w FetchProc—HookDispatch 7; FetchHook = 2 
dc.w VernierProc-HookDispatch ; VexrnierHook = 4 
dc.w ProjectProc—HookDispatch ; ProjectHook = 6 


There are a number of different changes that can be made to the comparison routines. 
Some of the common modifications include: 


1. | Comparing two bytes as one character 


Yugoslavian “I” < “lj” < “m”; Japanese... [InitProc, FetchProc] 
2. Comparing characters in different order 
Norwegian “z” < “a” [ProjectProc] 
3. | Comparing one character as two 
German “a” = “ae” [ProjectProc] 
4. ignoring characters unless strings are otherwise equal: 
“blackbird” < “black-bird” < “blackbirds” [ProjectProc] 
5. Changing the secondary ordering 
Bibliographic “a” < “A” | fVernierProc} 


The comparison hook procedures are all assembly language based, with arguments 
described below. Since the routines may be called once per character in both strings, 
the routines should be as fast as possible. 


The condition codes are used to return information about the status of the hook routine. 
Typically the normal processing of characters will be skipped if the CCR is set to NE, SO 
the default return should always have EQ set. Each of these routines has access to the 
stack frame (A6) used in the comparison routine, which has the following form: 


IUSortFrame Record {oldA6}, Decrement 

result ds.w 1 

argTop equ - 

aStrText ds.l 1 

bStrText ds.i 1 

aStrLen dads .w 1 

bStrLen ds.w 1 

argSize equ argTop-* 

return ds.l 1 

o1ldA6 ds.1l 1 

aInfo ds IuStrData 

binfo ds TUStrData 

wantMag ds.b 1 ; 1-MagStrig 0-MagIdString. 
weakEq ds.b 1 ; Signals at most weak equality 


Technical Note #178 page 2 of8 Modifying the Standard String Comparison 


msLock ds.b 1 high byte of master ptr. 


weakMag ds.b 1 ; -1 weak, 1 strong compare 
supStorage ds.b 18 ; extra storage. 
localSize equ ; frame size. 

EndR 


There are three fields in this frame that are of interest for altering text comparison. The 
supStorage field is an area reserved for use by the comparison hook procedures as 
they see fit. The alInfo and bInfo records contain information about the current byte 
positions in the two compared strings A and B, and information about the status of 
current characters in those string. The 1uSt rData record has the following form: 


IustrData Record 0 
curChar ds .w 1 ; current character. 
mapChar ds .w 1 ; projected character. 
decChar ds.w 1 ; decision char for weak equality 
bufChar ds.b 1 ; buffer for expansion. 
justAfter ds.b 1 ; boolean for AE vs ligature-AE. 
ignChar ds.b i ; flag: ignore char. 
noFetch ds.b 1 ; flag: no fetch of next. 
strCnt ds.w 1 ; length word. 
strPtr ds.1 1 ; current ptr to string. 
EndR 


The Init Procedure 


The Init Procedure is used to initialize the comparison process. The main use for this 
procedure is for double-byte scripts. As an optimization, the International Utilities will 
perform an initial check on the two strings, comparing for simple byte-to-byte equality. 
Thus any common initial substrings are checked before the Init procedure is called. The 
string pointers and lengths in the ITuStrData records have been updated to point just 
past the common substrings. 


Languages such as Japanese or Yugoslavian, which may consider two bytes to be one 
character, may have to back up one byte, as shown below. 


+ wae ee eee SE eee ee eee SE Ee ewe ae ae DA D D UP e ie eee ee e a D aD ua am e ae u AS aa aD aD aD am ue ye a D aa aD ua ue e Aa aa ua a 


; Routine InitProc 

; Input AG Local Frame 

; Output CCR NE to skip entire sort (usually set EQ) 
; Trashes Standard regs: A0/A1/D0-D2 

; Function Initialize any special international hooks. 

- Double-byte scripts must synchronize AInfo.StrPtr & 
; Binfo.StrPtr here! 


; Note: this should also check for single-byte nigori or maru, as below 


InitProc 
move .W AStrLen(a6), d0 | ; A length 
sub.w AlInfo.StrcCnt (a6) ,d0 ; see if its changed 
beq.s @FixB ; A is done if not 
sub.1 #2,Sp ; return param 
move .1 AStrText (a6),-(sp) ; textBuf 


Technical Note #178 page 3 of8 Modifying the Standard String Comparison 


move .w 
_CharByte 
tst.w 
ble.s 
sub.1 
add.w 

@FixB 
move .w 
sub.w 
beq.s 
sub.1 
move.1 
move .w 
_CharByte 
tst.w 
blie.w 
sub.1 
add.w 

@QuitInit 
bra.s 
Endwith 


(sp) + 
@FixB 
#1,AInfo.StrPtr (A6) 
#1,AInfo.StrCnt (A6) 


BStrLen{a6), dd 
BInfo.StrCnt (a6) ,d0 
Quit Init 

#2, Sp 

BStrText (a6), -(sp) 
d0, -(sp) 


(sp) + 

@QuitInit 
#1,Binfo.StrPtr (A6) 
#1,BInfo.StrCnt (A6) 


ReturnEQ 


The Fetch Procedure 


textOffiset 


bd] 


; on character boundary? 
yes, continue 

adjust pointer 

adjust count 


we wp Se 


B length 

see if its changed 
B is done if not 
return param 
textBuf 

textOffset 


=e. 


we *e Be “Se We 


on character boundary? 
yes, continue 

adjust pointer 

; adjust count 


=e s mo 


return to the caller. 


~e 


The Fetch Procedure is used to fetch a character from a string, updating the pointer and 
length to reflect the remainder of the string. For example, the following code changes the 
text comparison for Yugoslavian: 


; Routine 
; Input 


; Output 


t 

; Trashes 
> Function 
; 


FetchProc 
tst.b 
bne.s 


move .W 
move .b 


lea 


@compareChar 
move .w 


Technical Note #178 


FetchProc 

A2 String Data Structure 

A3 String pointer (one past fetched char) 

A6 Local Frame 

D4. W Character: top byte is fetched character, bottom 
is zero 

D5.B 1 if string is empty, otherwise 0 

D4.W Character: top byte set to character, bottom to 
extension 

DS.B 1 if string is empty, otherwise 0 


Standard regs: 


AQ /A1/D0-D2 


This routine returns the characters that are fetched from 
the string, if they are not just a sequence of single bytes. 


d5 
ReturnEq 


d4, d0 
(a3) ,a0 


pairTable,al 


(al)+,dl 


page 4 ofs 


; more characters in string? 
; no -> bail out. 


; load high byte. 
; load low byte. 


load table address 


; pair = 0? 


Modifying the Standard String Comparison 


beq.s ReturnEq ; yes -> end of table. 

cmp .w dQ,dl ; legal character pair? 

bne.s @compareChar ; no -> try the next one. 

add.w #1,a3 ; increment pointer. 

sub.w #1, StrCnt (a2) :; decrement length. 

addx.w d5,d5 ; empty -> set the flag. 

move .w a0, d4 ; copy character pair. 

rts ; return to caller with CCR=NE 
pairTable 

de .b "Ly! ; Lj 

de.b 'LJ' ; LJ 

dce.bp '1g' ; ld 

dc.b a Hs a 7; 13 

de.b 'Nj' ; Nj 

dc.b 'NJ' ; NJ 

dce. b 'ng' ; ng 

dc.b in! ; nj 

dc.b 'D', $be ; Dz-hat 

dce.b 'D', Sae 7; DZ-hat 

dc.b td', Sae ; dzZ—-hat 

dc.b 'd', S$be ; dz-hat 

DC.B $00, $00 ; table end 


The same sort of procedure is used for Japanese or other double-byte scripts, in order to 
combine two bytes into a single character for comparison. 


FetchProc 
with LUStrData 
tst.b d5 ; empty string? 
bne.s ReturnEg ; exit if length = 0 


; if we have a double-byte char, add the second byte 


lea CurChar (a2),a0 ; pass pointer 

move .wW d4, (a0) 7; set value at ptr 

clr.w d0 ; pass length 

sub.l #2, SP ; allocate return 

move.l a0,- (sp) ; pointer 

move .W d0,-(sp) ; offset 

_CharByte 

tst.w (sp) t+ ; test return 

bmi.s @DoubleByte ; skip if high byte (first two) 


: we don’t have a double byte, but two special cases combine second bytes 


move .b (a3) ,da0 ; get next byte 

cmp .b #SDE,d0 ; nigori? 

beq.s @DoubleByte ; add in 

cmp .b #$DF, d0 ; maru? 

bne.s ReturnEq ; exit: single byte 
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@DoubleByte 


move .b (a3)+,d4 ; get next byte 

subq.w #1,StrCnt (A2) ; dec string length 
addx.w d5,da5 ; set x=1 if string len = 0 

rts ; return to caller with CCR=NE 


The Project Procedure 


The Project Procedure is used to find the primary ordering for a character. This routine 
will map characters that differ only in the secondary ordering onto a single character, 
typically the unmodified, uppercase character. For example, the following changes the 
comparison order for some Norwegian characters, so that they occur after the character 


P an ee ee ee ee ee es ee ee ee ees ees ee ee es ee ee a a a ee es ee ees ee ees ee es ee a es ss es es es es es es es ee es es ee es es ee ae i ‘l 


; Routine ProjectProc 

; Input A2 String Data Structure 

; D4.W Character (top byte is char, bottom is extension 
; (the extension is zero unless set by FetchProc) ) 
; Output D4.W Projected Character 

; CCR NE to skip normal Project 

; Trashes Standard regs: A0/A1/D0-D2 

; Function This routine projects the secondary characters onto primary 
; characters. 


Example: a,4,A -> A 


> an oe ee ee ee UT ees ee ees ees ee ia ee ee ees ee ee ee ie as a es ee ee ee ee ee ee ee ee ee ea a ee a ee ee ee ee ee ee ee ae ee eee eee ee ee ű— 


ProjectProc 
lea ProjTable,Al ; load table address. 
@findChar 
move .1 (al)+,D0 ; get entry 
cmp.w d0, d4 ; original 2 entry? 
bhi.s @findChar ; no, try the next entry. 
bne.s ReturnEq ; not equal, process normally 
@replaceChar 
Swap do ; get replacement 
move .w d0, d4 ; set new character word. 
@doneChar 
rts ; CCR is NE to skip project. 
ProjTable 
: Table contains entries of the form ri, r2, ol, o2, 
: where r1,r2 are the replacement word, and 
; ol, o2 are the original character. 
; The entries are sorted by 01,02 for use in the above algorithm 
DC.B "2", 3, ‘A’, 0 ; A after @ 
DC.B "7"; 3; “at, 0 ; å after Ø 
DC.B ear Lg ay U ; after Z 
DC.B "Zt -ae (Os: OB ; Ø after 
DC.B oe dae Te j- after Z 
DC.B tat ar “Oe OU ; @ after 
DC.L SFFFFFFFF 7; table end 
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The Project procedure can also be used to undo the effects of the normal projection. For 
example, suppose that “ce” is not to be expanded into “oe”: in that case, a simple test 
can be made against ‘ce’,0, returning NE if there is a match, so that the normal processing 
is not done. 


To expand one character into two, the routine should return the first replacement 
character in D4.w, and modify two fields in the IustrData field. For example, given that 
Al points to a table entry of the form (primaryCharacter: Word; secondaryCharacters: 
Word), the following code could be used: 


move .w (al) +,da4 ; return first, primary character 


move .w (al) +, CurChar (A2) ; original => first, modified 
char. 

addq.b #1, JustAfter (A2) ; set to one (otherwise zero) 

move .b (al) , BufChar (A2) > store second character (BYTE!) 


CurChar is where the original character returned by Fet chChar is stored. If characters 
are different even after being projected onto their respective primary characters, then the 
CurChar values for each string will be compared. JustAfter indicates that the 
expanded character should sort after the corresponding unexpanded form. This field 
must be set whenever CurChar is modified in order for the comparison to be fully 
ordered. BufChar stores the next byte to be retrieved from the string by FetchChar. 


To handle the case where characters are ignored unless the two compared strings are 
otherwise equal, the IgnChar flag can be set. This can be used to handle characters 
such as the hyphen in English, or vowels in Arabic. 


cmp .w #hyphen, d0 ; is it a ignorable? 
seq IgnChar (a2) ; set whether or not 


The Vernier Procedure 


The Vernier Procedure is used to make a final comparison among characters that have 
the same primary ordering. It is only needed if the CurChar values are not ordered 
properly. For example, according to the binary encoding, å < A. To change this ordering 
so that uppercase letters are before lowercase letters, A is mapped to $7F in normal 
comparison. Notice that only the characters in the secondary ordering are affected: A can 
be mapped onto Z, but not onto A, since that would cause a collision. 


+ a a m aa aa an rar OE ROE Owe eS a AD AD a ae a D aa ae sees SSE! S ED E aI a Me Aa Aa AD S A S S AA S S E 


- Routine VernierProc 


; Input D4.B High byte of character 
- D5.B Low byte of character 
; Output D4.B High byte of character 
j D5.B Low byte of character 
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: CCR NE if to skip standard Vernier 

; Trashes Standard regs: A0/A1/D0-D2 

; Function The Vernier routine compares characters within the secondary 
; ordering if two strings are otherwise equal. 

; Example: (a,A,A, 4) 


Ò mm m e ee es es es re Å ‘a 


VernierProc 
not .b d4 ; invert secondary ordering 
not.b d5 ; ditto for lower byte 
bra.s ReturnEq ; normal processing afterwards 


Installing an it12 resource 


To write an it12 resource, follow the guidelines in Technica! Note #110 for writing 
standalone code in MPW. The code should be written in assembly language, and it must 
follow the specifications given in this technical note or serious system errors could occur 
whenever string comparisons are made. 


The default comparison routine is in the it12 resource of the System file. In order to use 
a comparison routine other than the standard one, you should include an it12 resource 
in your application with the same name and resource ID as the one in the System file 
that you wish to change. The Resource Manager will look for the resource in the 
application resource file before it looks in the System resource file, so your string 
comparison routine will be used instead of the default one. 


It is generally a dangerous practice to change a system resource since other 
applications may depend on it, but if you have good reasons to permanently change the 
system it12 resource so that all applications use a different comparison routine, then 
you should write an installer script to change the it 12 resource in the System resource 
file. Writing an installer script is documented in Technical Notes #75 and #76. You are 
required to write an installer script if you are planning to ship your application on a 
licensed system software disk and your application makes a permanent change to any 
resources in the System file. We strongly discourage changing the System it12 as that 
would change the behavior of string comparison and sorting for all applications. If that is 
your intent, then you should write an installer script. However, if you are changing the 
it12 resource in the System file for academic or internal use, then you can use a 
resource editor such as ResEdit to copy your it12 resource into the System file. 
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#179: Setting ioNamePtr in File Manager Calls 
See also: The File Manager 


Written by: Jim Friedlander November 2, 1987 





SS 


it is very important to set ioNamePt r when making PB calls, even if you don’t want those 
calls to return a name. Whenever Inside Macintosh indicates that ioNamePtr is either 
required for input or returns something, you must set ioNamePtr to either nil (if you 
arent using a name) or to point to storage for a Str255. 


If you don’t explicitly set ioNamePtr, strange and unusual crashes may occur, 
depending on the machine/configuration your code is run on. 
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#180: MultiFinder Miscellanea 


See also: Technical Note #126—Sublaunching 
Technical Note #158—Frequently Asked MultiFinder 
Questions 
Written by: Jim Friedlander November 2, 1987 





ee 


This Technical Note discusses various MultiFinder issues of which 
programmers should be aware. 





Desk Accessories and MultiFinder 


There is a persistent rumor that DAs no longer function under MultiFinder. While we are 
certainly encouraging people who write DAs to write small applications instead (it’s a lot 
easier to write a small application than a DA), MultiFinder 1.0 does indeed support the 
Standard desk accessory model. The world of the DA has changed somewhat, though, 
under MultiFinder. 


The major change is that DAs are now loaded into the system heap, instead of the 
application heap. This fact means that certain DAs will not work under MultiFinder 1.0, 
though we've gone to great lengths to make sure that most DAs will work correctly. DAs 
that are “self-sufficient” will work just fine. 


Self-sufficient DAs 


“Self-sufficient DAs” are DAs that don’t rely on a specific application being present in 
order to function, that is, they don’t rely on being in a specific application’s heap in order 
to do what they do. A self-sufficient DA also doesn’t care about global context at 
accEvent Or accRun time (not guaranteed under MultiFinder) since it is only drawing to 
its own window and dealing with its own storage. Under MultiFinder, a DA has no way of 
knowing who called it. 


Non self-sufficient DAs 


So, you’re probably wondering, what in the heck is a DA that isn’t self-sufficient. A good 
example of a DA that won't work very well under MultiFinder is a spell checker. Spell 
check DAs generally rely on posting events to get word processors to save to the scrap 
so the DA can then get the text from the scrap and scan it for speling erors. 
Unfortunately, at accEvent Of accRun time, you don’t know which MultiFinder partition 
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called you, so you can’t post an event (you don’t know where it will go) so you can’t get 
the text, so you get hopelessly confused and give up. 
Error checking 


DAs still need to do robust error checking to see if they have enough memory to load, 
even though MultiFinder loads DAs into the system heap, and will automatically grow the 
system heap if it can. A DA can’t know if MultiFinder has loaded it, or (even if MultiFinder 
has loaded it) if there is room to grow the system heap. A DA can check to see if there is 
room for it to load by actually trying to allocate all the memory it needs and then backing 
out gracefully if it can’t get it. 


Switching 


For conceptual clarity, it is best to think of MultiFinder 1.0 as using three types of 
switching: major, minor and update. All switching occurs at a very well defined time, 
namely when either WaitNextEvent, GetNextEvent or EventAvail is called. 


Major switching is a complete context switch, that is, an application’s windows are 
moved from the background to the foreground or rice-a-roni. A5 worlds are switched and 
the application’s low-memory world is switched. If the application accepts 
Suspend/Resume events, it is so notified at major switch time. 


Major switching will not occur when a modal dialog is the frontmost window of the front 
layer, though minor and update switching will. To determine this, MultiFinder looks to 
see (among other things) if the window definition procedure of that window is dBoxProc. 
if it is, then it won't allow a switch via the user clicking on another application. 
dBoxProcs are specifically reserved for modal dialogs—when most users see a 
dBoxProc, they are expecting a modal situation. If you are using a dBoxProc fora 
non-modal window, we’d strongly recommend that you change it to some other window 
type, or risk the wrath of the User-Interface Thought Police (UITP). 


Minor switching occurs when an application needs to be switched out in order to give 
time to background processes. In a minor switch, A5 worlds are switched, as are 
low-memory worlds, but the application’s layer of windows is not switched, and the 
application won't be notified of the switch via Suspend/Resume events. 


Update switching occurs when MultiFinder detects that one or more of the windows of 
an application that is not frontmost needs updating. This happens whether or not the 
application has the canBackground bit in the SIZE -1 resource. This switch is very 
similar to minor switching, except that update events are sent to the application whose 
window(s) need updating. 

Both minor and update switches should be transparent to the frontmost application. 
Suspend/Resume events 


lf your application does not accept Suspend/Resume events (as set in the SIZE —1 
resource), then if a mouseclick occurs in a window that isn’t yours, MultiFinder will send 
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your application a mouse-down event with code inMenuBar (with menuID equal to the 
ID of the Apple menu and menuItem set to “About MultiFinder ...”). The reason that 
MultiFinder does this is to force your application to think that a DA is coming up, so that it 
will convert any private scrap that it might be keeping. MultiFinder is expecting your 
application to call MenuSelect—if you don’t, it will currently issue a few more 
mouseDowns in the menu bar and then finally give up. This isn’t really a problem, but a 
lot of developers have run into it, especially in quick and dirty applications. 


If you are switching menu bars with SetMenuBar (and switching the Apple Menu) during 
the execution of your application, then you should definitely make sure that your 
application accepts Suspend/Resume events. MultiFinder records the 1D of the original 
Apple menu that you use and won't keep track of any changes that you make to the 
Apple menu. So, in the above situation, MultiFinder will give you a mouseDown in the 
menuBar with the menuItem Set to the item number of “About MultiFinder...” that was in 
the original Apple menu, which could be quite a confusing situation. If you set the 
MultiFinder friendly bitin the SIZE resource, MultiFinder will never give you these 
mouse down events. 


Referencing global data (A5 and MultiFinder) 


MultiFinder maintains a separate A5 world for each application. MultiFinder will switch 
A5 worlds as appropriate so most applications don’t have to worry about A5 at all (except 
to make sure that it points to a valid QuickDraw global record at GNE/WNE time). 
MultiFinder also switches low-memory globals for you, so, if you need to get at 
CurrentA5, you should be OK. 


lf an application uses routines that execute at interrupt time, then it does need to be 
concerned about a5. There are four basic types of interrupt routines that are affected by 
MultiFinder: 


VBL tasks 

«Completion routines 
Time manager tasks 
«Interrupt service routines 


from VBL tasks ’ 


If an application installs a VBL task into its application heap, MultiFinder will currently 
“unhook” that VBL routine when it switches that application out (using either a major or a 
minor switch). It will “rehook” it when the application is switched back in. A VBL task that 
is installed in the system heap will always receive time, that is, it will never be 
“unhooked.” Given this, it is technically not necessary for a VBL task that is in the 
application's heap to worry about its A5 context, since it will only be running when that 
application’s partition is switched in. However, we would still like to encourage you to 
set up A5 by carrying the value for CurrentA5 around with you, since we may change 
the way this works in future versions of MultiFinder (and even without MultiFinder the 
VBL could trigger at a time when AS is not correct). 
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The following short MPW Pascal example shows how to do this using INLINEs. Please 
note that this technique does not involve writing into your code segment (we'll get to that 
later), we just put our value of CurrentA5 in a position where we can find it from our 
VBLtask. This example relies on the fact that we know that Ao points to our VBLTask. 
Since we store our CurrentA5 into the 4 bytes before our vBLTask, we know that we 
can get Our CurrentA5 from -4 (A0). 


This example also serves to demonstrate how one might write a completion routine for 
an asynchronous Device Manager call. It is not intended to be a complete program, nor 
to demonstrate optimal techniques for displaying information (it uses Write 1nWindow). 


PROGRAM InlineVBEL; 


USES 
{ SPUSH} {save current compiler options} 
{SLOAD PasDump.dump} {load symbol table dump} 
Memtypes, QuickDraw, OSIntf, ToolIntf, PackIntf,MacPrint, WLW, JimLib; 
{$LOAD} {turn off LOAD} 
{$POP} {restore compiler options} 
{$D+} {debug symbols} 
CONST 
Interval = 6; {how often we want our VBL called, in ticks} 
CurrentaAs = $904; {low~memory global} 
TYPE 
MyVBLType = RECORD 
CurAS: Longint; {put CurA5 where we can find it) 
MyVBL: VBLTask; {the actual VBLTask} 
END; {MyVBLType } 
VAR 
Err : Integer; 
MyVBLRec : MyVBLType; 
Counter : Integer; 
MyEvent : EventRecord; 
PROCEDURE _DatalInit; 
EXTERNAL? 
PROCEDURE PushA5; 
INLINE $2F0D; {MOVE.L A5,-(SP)} {Push A5 onto the Stack} 
PROCEDURE PopAS; 


INLINE S2A5F; {MOVE.L (SP)+,A5} {Pop the stack into A5} 


PROCEDURE GetMyA5; 
INLINE $2A68,SFFFC; {MOVE.L -4(A0),A5} {Get the value of A5 we've 

stored before the parameter block and put 

it in A5. Since we know that when 

VBL task is called, AO will 

point to our parameter block, we 

also know that the value of CurrentA5 that 

we stored will be at ~4({A0)} 


PROCEDURE DoVBL; {our whizzy VBL task} 


BEGIN {DoVBL} 
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{First, we’ll make sure that we have our A5, that we stored before our 
parameter block} 

PushA5; {Push the value of A5 onto the stack} 

GetMyA5; {Get our A5 from right before the parameter block} 


{now we can access our globals: } 
MyVBLRec.MyYVBL.vblCount := Interval; {we wish to run again} 


Counter := Counter + 1; {to show we can set a global} 


{since we're leaving, put back the A5 that was there before we changed it} 


PopA5; {put back original A5} 
END; , {DoVBL} 
(Se eee a ee a ee ae ee ee } 
BEGIN {main PROGRAM) 
MaxAppl]Zone; {grow the heap to ApplLimit)} 
UnloadSeg(@ DatalInit); {unload data init code before any allocations) 
InitMac; {initialize Macintosh managers} 
InitWW (NIL); {initialize WritelnWindow with default window} 
Counter := 0; {initialize this) 


WITH MyVBLRec,MyVBL DO BEGIN 
CurAS := LongPtr(CurrentA5)*;{Get the current value of CurrenA5} 
vblAddr := @DoVBL; {point to our task} 
vblCount := Interval; 

{set up the interval at which we’]l be called} 

qType := ORD({(vType) ; {this to is necessary} 
vblPhase := 0; 

END; {With} 


Err := VIinstall(@MyVBLRec.MyVBL); {Install our VBLTask} 


writeln{'VInstall err = ',Err); 
REPEAT 
writein (Counter)? {write out counter} 


UNTIL GetNextEvent (mDownMask,MyEvent); {this allows a switch} 


Err := VRemove (@MyVBLRec.MyVBL)s{we’re done, remove the task} 
writeln{'VRemove err = ', Err); 


beep; {show ‘em we're done} 
END. 


from Completion routines 


Currently, MuttiFinder will not do a major, minor, or update switch if an asynchronous 
File Manager call is pending, so an application doesn’t really need to worry about 
whether or not its A5 or low-memory globals are correct, but we still recommend that you 
use the above technique to save A5 for asynchronous File Manager calls. MultiFinder 
will, however, switch if an asynchronous Device Manager call is pending. When the 
call completes, the completion routine has no way of knowing whose partition is active, 
that is, it doesn’t know if A5 is valid (it needs A5 if it wants to set a global) or even if the 
value of CurrentAS5 is valid. Sounds pretty hopeless, huh? 


Well, actually this one is quite easy, you just need to put the value of Currentas that 
“belongs” to your partition in a place where you can find it from your completion routine. 
Since it is guaranteed that AO will be pointing to your parameter block when your 
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the beginning of your parameter block and then reference it off of AO. Completion 
routines are normally written in assembly language, though you can also write them in a 
high-level language. A simple example of how to do this from MPW Pascal can be found 
in the previous section about VBL tasks (it was a little easier to provide a clear, concise 
example for VBLs than for asynchronous Device Manager completion routines). 


from Time Manager Tasks 


You might think that you could use the same technique for Time Manager tasks as for 
VBL tasks, but, unfortunately you can't. Unlike VBL tasks (and completion routines), a 
Time Manager task is not called with ao pointing to the task block (AO points to the task’s 
routine instead). So, if you need to get at your application’s globals from your Time 
Manager task, you'll have to actually write the value of CurrentaA5 into your code 
segment at a time when you know that Currents is valid and then use that value to set 
up A5 when your Time Manager task is called. (I know, I know: Technical Note #2 says 
not to do this, but there’s no alternative in this case). 


from Interrupt service routines 


lf your application needs to get to its application globals and it replaces the standard 
68xxx interrupt vectors (levels 1-7) with pointers to its own routines, it must also write 
Currentas into its code (since there is no parameter block for interrupt service routines). 


Note: WDEFs should also carry around a copy of A5 in the same fashion as Time 
Manager tasks and set up a5 when called; WDEFs should also be non-purgeable. 


Launching and MultiFinder 


Technical Note #126 (revised, July 1, 1987) discusses the sublaunching feature of 
System 4.1. If you are running MultiFinder and you use the technique demonstrated in 
that technical note, your application will be able to launch the desired application and 
remain open. Note: MultiFinder does not support Chain, so your application should 
never call this trap. 


The application that you launch will become the foreground application. Unlike 
non-MultiFinder systems, when the user quits the application that you have 
sublaunched, control will not necessarily return to your application, but rather to the next 
frontmost layer. 


Unlike non-MultiFinder systems, if you set both high bits of LaunchFlags, your 
application will continue to execute after calling Launch, So be prepared! Calling 
_Launch with both high bits of LaunchFlags set can be thought of as a request to 
sublaunch an application. The actual launch (and hence SUSPEND of your application) 
won't happen in the Launch trap, but at a later time (after a call or two to 
GNE/WNE/EventAvail). 


_ Launch under MultiFinder currently will return an error if there isn’t enough memory to 
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launch the desired application, if the desired application can't be located or if the desired 
application is already open. In the latter case, that application will not be made 
active—if you sublaunched, control will return to your application, if you didn’t sublaunch, 
your application will be terminated and the next frontmost layer will become active. If you 
didn't sublaunch and an error occurred, MultiFinder will do a SysBeep, since your 
application will be terminated. If you sublaunched, MultiFinder will not beep and it is up 
to your application to report the error to the user. 


_Launch now returns an error in register DO if you are sublaunching. You can check for 
DO<0 after the sublaunch to see ifthe Launch failed. If DO>=0 then the application will 
be launched. You could modify the code in Technical Note #126 to return an error as 
follows (in MPW Pascal): 


FUNCTION Launchit (pLnch: pLaunchStruct) :OSErr; 


INLINE S205F, {MOVE.L (SP)+,A0 ;pointer to parameters in A0} 
SASF2, { Launch} 
S3E80; {MOVE.W DO, (A7) ;get function result from D0} 


Note: The warnings in the technical note about using Sublaunching still apply, but, if 
you still wish to use Sublaunching, we strongly recommend that you set both high bits of 
LaunchF lags. 


The Scrap and MultiFinder 


MultiFinder 1.0 keeps separate scrap variables for each partition. MultiFinder only 
checks to see whether or not to increment the other partitions’ scrapCounts in response 
to a user-initiated Cut or Copy. To do this, it watches the SystemEdit call to determine 
whether an official Cut or Copy has been issued. 


When an application calls Put Scrap Of ZeroScrap in response to a Cut or Copy menu 
selection, the other partitions’ scrapCounts will be incremented (the other partitions will 
know that something new has been put in the scrap). 


System Resources and MultiFinder 


MultiFinder is a shared environment. Resources that were formerly loaded into the 
application heap can now be loaded into the system heap for use by all applications. 
Basically, if a resource came from the System file, then it will be loaded into the system 
heap, even if the resSysHeap bit isn't set. 


Since other applications may need to use system resources, applications should not call 
ReleaseResource Of DetachResource on system resources, such as cursors and 
fonts, nor should they change resource attributes or modify the resource data directly. 
Applications should also not make assumptions about where a resource has been 
loaded (system heap or application heap). 
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UnmountVol and MultiFinder 


UnmountVol was changed in System 4.2 so that it would work better in a shared 
environment. In systems 4.1 and prior, UnmountVol would successfully unmount a 
volume even if files were open on that volume. Under MultiFinder, that would be 
disastrous, since one application could unmount a volume that another application was 
using (this exact problem could occur under UniFinder if a DA unmounted a volume “out 
from under’ an application). 


System 4.2 changes the behavior of Unmount Vol (whether or not MultiFinder is running) 
so that it will return a -47 (FBsyErr) error if any files are open on the volume you wish to 
unmount. Since the Finder always has a DeskTop file open for each volume, it is asked 
to close the DeskTop file by Unmount Vol, so you won't get an error back if the only file 
open on a volume is the DeskTop file. 


Putting up a splash screen 


Some applications like to put up a “splash screen” to give the user something to look at 
while the application is loading. If your application does this and has the 
canBackground bit set in the size resource, then it must call GetNextEvent several 
times (or WaitNextEvent Or EventAvail) before putting up the splash screen, or the 
splash screen will come up behind the frontmost layer. If the canBackground bit is set, 
MultiFinder will not move your layer to the front until you call GNE/WNE/EventAvail. 


The Apple Menu and MultiFinder 


Applications should avoid doing anything untoward with the Apple menu. For example, 
if your application puts an icon next to the “About MyApplication...” item, MultiFinder may 
unceremoniously write over it. 


Interprocess Communication 


MultiFinder 1.0 doesn’t have full-fledged interprocess communication facilities (that is 
planned for MultiFinder 2.0). 


There is no standard way to communicate between applications in MultiFinder 1.0. One 
of MultiFinder 1.0’s design goals was to not change the programming model (that is, so - 
that as few applications as possible would have to be altered to run under MultiFinder) 
so it was impossible to add meaningful IPC. 


There are, though, a couple of ways to communicate between applications. You can 
communicate through a file or through the clipboard (not guaranteed to be successful, 
since an intervening application might do a ZzeroScrap) or you could use a 
bulletin-board type driver, where one application sends a message to the driver, which 
records the message and another application can query the driver to see if any 
messages have arrived. You can also do IPC with AppleTalk. If you’re running 
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AppleTalk drivers version 48 or later you have the capability to send packets to your own 
node. This feature is enabled by making a SetSelfSend call. With AppleTalk self 
sending enabled, two applications on the same machine can send packets to each 
other. If you want to ensure that the socket you're sending data to is on your local 
machine, (as opposed to another machine on the network), you can check the node 
portion of the socket’s address you look up with NBP. Note: it is most definitely to your 
advantage to wait until we implement real IPC. | 


Running as a Background Application 


For applications that run in the background (i.e. applications that have the 
canBackground bit set in the SIZE resource), the programming model changes 
somewhat. Since background applications aren't guaranteed any time, an application 
that is running in the background should not count on being able to communicate with 
the user at any time. For example, a background application should not put up a modal 
dialog to inform the user that something that requires immediate attention has occurred 
(in fact, the modal dialog will not come up in the foreground, but rather behind other 
layers and the user might not be able to see the dialog at all). If an application does 
require urgent attention of the user, then it probably should not run in the background, or, 
at the least, should not perform any operation that may require urgent attention while it is 
in the background until notification services are provided in system software. 


Background applications also should not do anything that might affect the foreground 
application such as changing the cursor or altering the menu bar. 


Background applications do not receive user events of any kind. This includes 
application-defined events. if an application posts an application-defined event from the 
background, it will be sent to the foreground application (which will probably confuse that 
application). Rather than post an application-defined event, an application that is 
running in the background could set a global that is checked at Main Event Loop time to 
indicate a change in program status. 


Miscellaneous Miscellanea 


The sound glue that shipped with MPW 1.0 and 2.0 is not MultiFinder compatible and 
should not be used. Instead, applications should make direct calls to the sound driver. 


All code needs to be aware of the shared environment; this includes ScreenSavers. 
ScreenSavers should make sure that background processing continues. A simple 
scenario for a ScreenSaver that’s an INIT might be: patch PostEvent at INIT time, put 
up a full-screen black window spider, call WaitNextEvent, and watch PostEvent to 
see if an event that should cause the ScreenSaver to go away has occurred. 
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#181: Every Picture [Comment] Tells Its Story, Don’t It? 


see also: QuickDraw 
Technical Note #91—Optimizing for the LaserWriter— 
Picture Comments 
The Palette Manager 


Written by: Rick Blair November 2, 1987 





The problem of application-specific picture comment conflict and registration 
is addressed, along with Macintosh Technical Support’s method for solving it. 





—— hee 


| will assume that the nature and usefulness of picture comments are already well 
known. The problem | am addressing is that, as it stands, developers must register their 
comments with us (Developer Technical Support) or run the risk of using the same 
comments as those used by Apple or within another third party product. 


The idea here is to provide a “metacomment” which will contain information about which 
application owns the comment as well as the comment itself: 


ApplicationComment (long comment) kind = 100 size =n + 6 
data = application signature (i.e. 'MPNT' for MacPaint) = 4 bytes 
application “local” kind = 2 bytes 
comment data = n bytes 


In this way each comment may be specific to an application. It is still up to a developer to 
publish information about the comments they have defined if they wish them to be 
understood and used by other programs. 


Previously assigned and registered comments will still be valid. This means that those 
defined for the LaserWriter or MacDraw, for instance, will retain their normal meaning. 


Suppose your application (creator = 'myar') wanted to define a “here’s a palette” 
comment. This would allow any application which knew about your comments to read in 
and set a palette onto the window that was being used for the picture. You would have 
this comment right at the start of the PICT. The wise application wouid then transfer the 
palette data into a memory biock and use SetPalette. The appearance of the comment 
would be as follows (assuming you chose 128 to be the “local” kind for the comment): 


kind = 100; data = 'MYAP' [4 bytes] + 128 [2 bytes] + palette data 
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#182: How to Construct Word-Break Tables 
See also: The Script Manager 
Written by: Mark Davis November 2, 1987 


This technical note describes how to construct auxiliary break tables for use 
with the FindWord routine in the Script Manager. 


Constructing break tables 


The FindWord algorithm finds word boundaries by determining where words should not 
be broken. For example, “re-do” is one word: it should not be broken at the hyphen. In 
other words, a sequence of the form: (letter, hyphen, letter) should not be broken 
between the first and second or second and third character. This is called a continuation 
sequence. The algorithm used by the FindWord routine allows for continuation 
sequences of lengths one, two and three. Examples of a sequence of length two include 
(letter, letter), or (number, number). For a length of one, there is only one sequence, 
consisting of the characters of type nonBreaking: these characters are never separated 
from preceding or following characters. 


For most scripts, this information about continuation sequences is packed into a table for 
use by the FindWord algorithm. (For complex scripts like Japanese, a different algorithm 
is used for portions of the script.) The default break tables for a given script can be 
overridden by a user-specified breakTable parameter, but should only be used for 
known scripts. That is, before overriding the breakTable parameter, the programmer 
should first check the script of the current font. 


A break table consists of two sections, a 256 byte character type table followed by a 
character triple table. 
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$30 | 


Character Type Table 
$40 


$42 





$FE f 


Character Triple Table 





The character type table is indexed by the character's ASCII code and contains one type 
value for each character. The character types in the table are limited to values between 1 
and 31. There are two distinguishing values: the type nonBreaking (= 1) indicates that 
the character is non-breaking; it always continues a word. The type wild (=0) indicates 
that the character may or may not break, depending on information in the character triple 
table, as described below. Otherwise, the choice of numbers to represent character 
types is completely arbitrary. 


For example, the following in MPW Assembler defines character types for use in a 
word-selection break table, then sets up a character type table using an assembly macro 
(set Byte) to store character type values in an array. (Note that the character types 
could have been defined with equate definitions (EQU), rather than using the record 
structure.) Writing the setByte macro is left as an exercise to the reader. Note that the 
break value is the default. This value is not distinguished, but should have no 
continuation sequences. 
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charWordRec record 0 
wild ds.b 1 ; constant! not in char table. 
nonbreak ds.b 1 ; constant! non-breaking space. 
letter ds.b 1 ; letters. 
number ds.b 1 ; digits. 
break ds.b 1 ; always breaks. 
midLetter ds .b 1 ; a'a. 
midLetNum ds.b 1 z; a'a 1'1. 
preNum ds.b 1 ; $, etc. 
postNum ds.b 1 7; %, etc. 
midNum das .b 1 = a 
preMidNum ds.b 1 ; .1234. 
blank ads.b 1 ; spaces and tabs. 
Cr ds.b 1 ; add carriage return 
endr 
with charWordRec 
wordTable 
dcb .b 256, break 
setByte wordTable, nonBreak, $ca 
setByte wordTable, letter, ('A','Z'), ('a','z') ('A', 'ii') 
setByte wordTable, letter, ' ','@'," ','o', ('A',' '),'¥' 
setByte wordTable,midLetter, '-' 
setByte wordTable, midLetNum, $27, ‘'' 
setByte wordTable, number, ('0', '9') 
setByte wordTable, preNum, '$', '¢', "£', '¥' 
setByte wordTable, postNum, '%' 
setByte wordTable,midNum, ', ' 
setByte wordTable, preMidNum, '.' 
setByte wordTable,blank,$00,' ‘',$09 
setByte wordTable,cr, $0d 
endwWith 


$ ee tenaa a aE SA aaa BREE S SS LS LS TS 


The character triple table is a coded representation of a list of continuation sequences. It 
consists of a list of packed one word triples, preceded by a length word. This length word 
contains the number of triples minus one. Each triple contains three character types, 
either as derived from the chartType table or the special type wild (= zero). The three 
types in a triple are packed into fields five bits apiece, with the most significant bit in the 
word cleared. The first type in the triple is the leftmost. 


A continuation sequence of length three (xyz) is represented by entering three triples into 
the triple list: xyz, *xy, and yz* (where *' stands for the type wild, which is always zero). 


hyphen} letter ~ 


A continuation sequence of length two (xy) is represented by entering two triples into this 
list: *xy, and xy*. A continuation sequence of length one has no entry in the triple list: the 
character type is simply nonBreaking. 
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Note that the type wild cannot appear as the middle element of a triple. The words in the 
triple table must be sorted in ascending numerical order for future compatibility. 


The following is an example of how a character triple table could be coded. The defSeq 
macro takes a continuation sequence as a parameter, and enters a set of triples into an 
internal array. The dumpSeq macro sorts the triples, and stores them in the proper order 
with dc.w commands. Once again, writing the macros defSeq and dumpSegq is left as an 
exercise for the reader. 


; 22o Eaa annn a a a E e a r a E E O SA SS a I t Ak SL SSE ES ESE e E 


with charWordRec 
defSeq letter, letter 
defSeq letter, preMidNum, letter 
defSeq letter,midLetter, letter 
defSeq letter,midLetNum, letter 
defSeq number, number 
defSeq number, letter 
defSeq number, midNum, number 
defSeq number, midLetNum, number 
defSeq number, preMidNum, number 
defSeq number, postNum 
defSeq preNum, number 
defSeq preMidNum, number 
defSeq blank, blank 
defSeq blank,cr 
endwith 
dc.w ( (wordEnd-wordBegin) /2)-1 ; length word. 
wordBegin 
dumpSeq 
wordEnd 


; "FTO a a i SESS SS ST SSE SE SBR Ll Es TET VSO SL SIE bp 4 — tt E 


A series of blanks should generally select as a single word. Make certain, however, that 
a carriage return does not continue a word to the right (note how it has a separate 
character type from blank for this reason), otherwise word selection and wrapping do not 
work properly across paragraphs. 


Extensions 
The values 16-31 in the character type table entry for null ($00) (the first byte in the 


character type table) are reserved by Apple for future expansion. The use of one of these 
values indicates the presence of a supplementary table after the triple table. 
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#183: Position Independent PostScript 


See also: The Print Manager 
QuickDraw 
LaserWriter Reference Manual 
Technical Note #91: Optimizing for the LaserWriter— 
PicComments 
PostScript Language Reference Manual, Adobe Systems 
PostScript Language Cookbook and Tutorial, Adobe Systems 


Written by: scott “ZZ” Zimmerman November 2, 1987 





This technical note describes a method for inserting position independent 
PostScript into QuickDraw pictures. 


There is a problem with pictures that contain PostScript code. Sometimes the PostScript 
code that is inserted into the picture is dependent on the position of the picture on the 
page. The problem arises when these pictures are cut or copied from their original 
position, and pasted into another position or even into another document. The PostScript 
code will not know the new location of the picture, and will not execute correctly. 


The solution for this problem, is to provide some way for the PostScript code to determine 
the current location of the picture relative to the page that it is being printed on. This is 
done by inserting QuickDraw calls to position the LaserWriter’s pen before inserting the 
position dependent PostScript code. When the PostScript in the picture is executed, the 
LaserWriter’s pen location will be in a location relative to the position of the picture on the 


page. 


The following example illustrates a method for positioning the LaserWriter’s pen before 
inserting any PostScript code into the picture. The method uses QuickDraw calls to 
position the LaserWriter’s pen, and will work with any application that supports 
QuickDraw pictures. Applications do not have to be changed to be able to take 
advantage of this technique. ? 


The following code fragment will create a picture that contains PostScript to draw a 
rectangle around the picture’s frame: 
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FUNCTION CreatePicture(pictureRect: Rect): PicHandle; 


CONST 


VAR 


BEGIN 


PostScriptBegin = 190; 
PostScriptEnd = 191; 
PostScriptHandle = 192; 


PSString + SErZ50; 
PSHandle : Handle; 
theError . OSErr; 


(* Create a new Picture. *) 
CreatePicture := OpenPicture(pictureRect) ; 
ClipRect (pictureRect) ; 


(* Set the pen size to 0,0 so the following Line will not *) 
(* be shown, it is only sent to position the pen.*) 
PenSize (0,0); 


(* Move the QuickDraw pen to the first pixel inside the *) 
(* the picture’s frame. This by itself will not *) 

(* change the LaserWriter’s pen location! *) 

MoveTo (pictureRect .left, pictureRect .top); 


(* Force the LaserWriter’s pen location to match the *) 

(* QuickDraw pen location. Actually any drawing command, *) 
(* such as LineTo or even DrawString will cause the *) 

(* LaserWriter’s pen location to change. This call to *) 

(* the Line procedure only causes the coordinates of *) 

(* the above MoveTo to be fiushed to the LaserWriter. *) 

(* Because of the PenSize call above, no Line is drawn. *) 
Line (0,0); 


(* Reset the pen to its default size. *) 
PenSize (1,1); 


(* The LaserWriter’s pen location has now been changed. The *) 
(* PostScript currentpoint operator will now return the *) 

(* location of the center pixel of the Picture. *) 

(* Get the PostScript ready to be sent. *) 


(* currentpoint - push the current Point onto the stack. *) 
(* newpath - Begin a new Line segment. *) 

(* MoveTo - Move to the currentpoint we saved above. *) 
(* nn nn rlineto - frame the Picture with lines. *) 

{* stroke - Draw the frame. *) 


PSString := 
'100 0 rlineto 0 100 rlineto -100 0 rlineto 0 -100 rlineto stroke 


i 

PSString[{length(PSString)] := CHR(13); (* Don’t forget CR. *) 

theError:=PtrToHand (Ptr (ORD4(@PSString) +1), 
PSHandle, length (PSString) ); 

IF theError <> noErr THEN HandleError; 


(* Send the PostScript code to the LaserWriter. *) 
PicComment (PostScriptBegin, 0,nil); 


(* QuickDraw calls made between the PostScriptBegin *) 
(* and PostScriptEnd PicComments will be ignored by *) 
(* devices that support PostScript. *) 
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PicComment (PostScriptHandle, GetHandleSize (PSHandle) , PSHandle) ; 
PicComment (PostScriptEnd,0,nil); 


(* Kill off the Handle we created and close the picture. *) 
DisposHandle (PSHandle) ; 
ClosePicture; 

END; (* CreatePicture *) 


See the LaserWriter Reference Manual for more information about PicComments. See 
the PostScript Language Reference Manual for more information about the 
currentpoint operator. 


There are some important guidelines to follow when sending PostScript directly to the 
LaserWriter. See the PostScript Commands section of Technical Note #91, for a 
complete description of these guidelines. 
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